Using REELlibrarian to read and write tapes on UNIX

1. Introduction - README
2. Syntax and Definitions
3. Using the full-screen interface
4. Checking the library, listing your volumesets and attributes
5. Requesting a scratch tape for writing
6. Mounting a tape, checking status of your mount
7. Checking a tape (tape map)
8. Detaching a tape
9. Reading a tape
10. Writing an archive (tar) tape
11. Writing a tape for export to an IBM system
12. Additional notes for writing tapes
13. Handling errors
14. Changing catalog information

    A. Setting volumesets for shared access

    B. Setting the record size

    C. Automatically converting to ascii

15. Releasing (scratching) a tape
16. Information about UDelVM labeled tapes

    A. Tapes with A and C reel numbers

    B. Tapes with B reel numbers

17. Complete examples

    Example 1: Mounting and reading a labeled tape.

    Example 2: Read 10 files from a labeled tape.

    Example 3: Mounting and reading an unlabeled tape.

    Example 4: Read 3 files from an unlabeled tape.

    Example 5: Read a data file into a SAS program.

    Example 6: Read a data file into a Fortran program.

    Example 7: Mounting and reading a tar tape.

    Example 8: Mounting and reading a Census or ICPSR tape.

    Example 9: Creating an archive (tar) tape for one directory.

    Example 10: Creating an archive (tar) tape for two directories.

    Example 11: Writing a labeled tape for export.

    Example 12: Writing a tape from a Fortran program.

1. Introduction - README

REELlibrarian software is available on all central UNIX composer systems except Copland. This software provides tape management facilities to catalog, identify, and track tapes, and to process tape mount requests. Commands to read and write tapes are also part of the software.

A full-screen interface is available to use for catalog maintenance and inquiry tasks. Use the command "rl" to invoke this interface. Further information is below in the section "Using the full-screen interface".

Output from the commands may be directed to a file. Commands, such as the read command, may be put into the background, using standard UNIX techniques.

If you leave the tape device idle for a period of time, REELlibrarian will reclaim the device and you will have to re-issue the mount request.

Man pages are available for further information about the commands. The REELlibrarian Master Guide manual is available in the Research & Data Management Services Lab (002C Smith).

2. Syntax and Definitions

In the text below, all values contained in angle braces must be replaced by appropriate values. For example, replace <correct internal label> by the label on the tape, such as A03453. Do not include the angle braces.

A "volumeset" is composed of one or more physical tapes called "volumes". Commands that apply to volumesets begin with the letters "rlv". For example, "rlvedit" is used to change attributes for volumesets.

The value <volset> is replaced by the "volumeset name". You may specify a volumeset name when you request a tape from the scratch pool for writing. This name may be any string up to 12 characters long. The default <volset> is a period followed by the tape reel number. For example, if you are assigned tape C22334 from the scratch pool, you may use .C22334 or the name you specified in the request command as the <volset>. For tapes submitted at the I/O Counter or transferred from the UDelVM tape library, the <volset> has been set to the tape reel number (formerly called the "volser"). For example, for tape U01001 submitted at the I/O Counter, you may use either U01001 or .U01001 as the <volset>.

The <vid> is replaced by the "volume name" which is the tape reel number.

3. Using the full-screen interface

With the full-screen interface, you may see your list of tapes and the tape attributes. You may also change the attributes. The command "rl" invokes the interface. If you are using a Sun workstation and a command tools window, you must turn off scrolling for the screens to display properly. Help is available, as indicated on the first screen, by pressing F2 or ctrl-B. To leave the full-screen interface, use the escape which is F1 or ctrl-A.

4. Checking the library, listing your volumesets and attributes

To see a list of the volumesets you have in the REELlibrarian catalog, use the command:

rlr   vslist

To check the attributes of a specific volumeset, use the command:

rlr   volset=<volset>   vinfo

For example,

rlr   volset=.A10100   vinfo

lists the information for volumeset .A10100.

If you use the full-screen interface, access the "Reports" function.

5. Requesting a scratch tape for writing

The scratch pool named "root/pub" is a set of tapes available for writing. You request a tape from the scratch pool using the command "rlvcreate". You may specify a <volset> to use to identify the tape. Output from the rlvcreate command reports the <vid> which is the number of the assigned tape. The default <volset> is a period followed by the <vid>. For example, if you are assigned tape number A22334 after you issue the rlvcreate command, you use the volumeset name you specified or .A22334 in commands requiring a <volset>.

You may set the format of the tape, the access permission, and other attributes in the "rlvcreate" command.

Command sample: requesting a tape for archive specifying a volumeset name and setting the mode for read access

rlvcreate  format=TAR  vmode=755  sept95

By default the tape will be a reel tape with density 6250. The "vmode" setting allows other users to see the catalog information for this tape and to mount this tape. Output from the rlvcreate command reports the assigned reel number, but you may use the volumeset name "sept95" to refer to this tape. Other users must preceed "sept95" with your username and a / (slash character).

Command sample: requesting a cartridge tape for archive

rlvcreate format=TAR type=3480 length=500

You request a cartridge ("3480") by specifying the "type" and "length" in the request. Output from the rlvcreate command reports the assigned reel number.

Command sample: requesting a tape to contain ebcdic files - unlabeled

rlvcreate format=IBMU conv=etext rformat=fb:8000:80

Files written to this tape will be padded with blanks to a record length of 80 characters. The "new line" characters will be stripped from the lines. The files will be written on the tape in ebcdic. The "rformat" defines the default value used to write the files on the tape, but a different value may be specified in the actual write command. Output from the rlvcreate command reports the assigned reel number.

Command sample: requesting a tape to contain ebcdic files - labeled

rlvcreate format=IBM conv=etext rformat=fb:1600:80 transtape

Files written to this tape will be padded with blanks to a record length of 80 characters. The "new line" characters will be stripped from the lines. The files will be written on the tape in ebcdic. The "rformat" defines the default value used to write the files on the tape, but a different value may be specified in the actual write command. Standard labels containing file identification information will be written on the tape. Output from the rlvcreate command reports the assigned reel number, but you may use the volumeset name "transtape" to refer to this tape.

6. Mounting a tape, checking status of your mount

You request a device for a tape mount using the command "rlvaccess". To mount the tape only for reading, use the command:

rlvaccess   <volset>

To mount the tape for writing, use the command:

rlvaccess   write=yes   <volset>

A tape mounted for writing may also be read. However, if you do not intend to write to the tape, the recommended mount is for read only. The message "Device Reserved" confirms your request.

To use a tape belonging to another person, the owner must set the mode to allow access. The <volset> used in the "rlvaccess" command may be either a period followed by the tape reel number or the username of the owner of the tape and a / (slash character) followed by the volumeset name. For example, if tape A14002 belonging to user "jodoe" has been unlocked for public access and has volumeset name "july2k", you may use either of the following commands:

rlvaccess   jodoe/july2k

rlvaccess   .A14002

The "rlvaccess" command reserves a device for you, but does not issue the mount request to the Operator. The mount request is issued when you enter a command which accesses the tape, such as "rlvdisplay", "rlvread", or "rlvwrite". When the mount request is sent to the Operator, you will receive the messages "Requesting tape <volset>...Awaiting Mount...". If the mount fails, see the "Handling errors" section below for help.

Please be aware that if you leave the tape device idle for a period of time, REELlibrarian will reclaim the drive from you and you will have to re-issue the "rlvaccess" command.

To check the status of your mount use the command:

rlstatus

To mount two volumesets, use the option "psd" with the second "rlvaccess" command:

rlvaccess   <volset>   <psd>

replacing <psd> with any name you choose. The <psd> will identify this volumeset in other following REELlibrarian commands. To mount volumesets A12345 and A12678, use the commands

rlvaccess   .A12345

rlvaccess   .A12678   tape2

7. Checking a tape (tape map)

Use the command "rlvdisplay" to list information about the contents of a volumeset.

For a multi-file labeled or unlabeled tape, use the command

rlvdisplay   rep=scan

to check the tape. For a labeled tape, the output will list the file name stored in the label plus the record and block size and number of blocks for each file. For an unlabeled tape, the output will list the number of blocks in each file. However, the record and block size reported are the default values in the catalog, not values determined from the tape. The number of blocks is reported for each file.

For a tar tape, use the command

rlvdisplay   rep=toc

to display information about the number of physical files on a tape. To see the names of the files contained in a tarfile, you must read the tape and pipe the output into the tar command. See the section "Reading a tape" for an example.

8. Detaching a tape

Use the command

rlvrelease

9. Reading a tape

You read a file from a volumeset using the "rlvread" command. You define how to read the file using keywords. In the command samples below, using the "of" keyword creates a file with security 666; using redirection creates a file with your standard security (probably 600). More examples are in the section "Complete examples" below.

Command sample: reading a labeled ebcdic tape defined with "format=IBM" - (1)

rlvread   fseq=3   of=FID   conv=etext

This command reads file 3 from a labeled tape and puts the output into a file with the name listed in the tape label. The data is converted to ascii using the record and block size recorded in the label, trailing blanks are removed, and each record is terminated with a nl (new line) character.

Command sample: reading a labeled ebcdic tape defined with "format=IBM" - (2)

rlvread   fseq=5   of=FID

This command reads file 5 from a labeled tape. The output file is assigned the name recorded on the tape. The data is converted as specified in the catalog.

Command sample: reading an unlabeled ebcdic tape defined with "format=IBMU" - (1)

rlvread   fseq=6   conv=etext   of=data0722   rformat=fb:8000:80

This command reads an ebcdic file from an unlabeled tape and converts it to ascii, using a format of 80 characters/record. The output file is named "data0722". Trailing blanks in each record are removed and each record is terminated with a nl (new line) character.

Command sample: reading an unlabeled ebcdic tape defined with "format=IBMU" - (2)

rlvread   fseq=1   of=tapefile

rlvread   fseq=1   >   tapefile

These commands read file 1 from the tape using the conversion specified in the catalog and place the file in "tapefile".

Command sample: reading an unlabeled ebcdic tape defined with "format=IBMU" - (3)

rlvread   fseq=1   conv=edata   of=fluid45

This command reads an ebcdic file and converts it to ascii. The records are not terminated with nl (new line) characters and the file appears as one long record to an editor. You can break up the file with dd if needed. The recommended way to read an ebcdic file is to use "conv=etext".

Command sample: reading the table of contents from a tar tape

rlvread   fseq=1   |   tar   tvf   -

This command will read the first file on the tape and print the table of contents listing the names of the saved files.

Command sample: reading one file from a tar tape

rlvread   fseq=1   |   tar xvf   -   rock.data

This command will read the first file on the tape and pass the data to the "tar" command. "Tar" will extract the file "rock.data" from the tarfile and place it in the current directory. Note that "tar" requires you to specify the file name exactly as it appears in the tarfile table of contents.

Command sample: reading a directory from a tar tape

rlvread   fseq=2   |   tar   xvf   -   sas.dir

This command will read the second file on a tar tape and pass the data to the "tar" command. The "tar" command will extract all files in the tarfile whose names begin with "sas.dir" and place them in a directory named "sas.dir". If the directory "sas.dir" does not exist, it will be created.

10. Writing an archive (tar) tape

"tar" is the UNIX utility to create archive files, called "tarfiles", and to extract files from a tarfile. This command is used together with the "rlvwrite" command to create archive tapes. To write a tarfile containing a single file named "ditest.f" to tape, use the command:

tar   cf  -  ditest.f  |  rlvwrite  fseq=1

The file will be written as file 1 on the tape. You may list several file names and use wildcards to create and write a tarfile containing several files. For example,

tar  cf  -  *.data  |  rlvwrite  fseq=1

will write all the files with extension ".data" into one tarfile on the tape. See the "tar" man page for more information.

To use the tar "v" function modifier and direct the output to a file, use the following form:

(tar   cvf  -   .   |  rlvwrite  fseq=1   >&!  rlout )   >&!  tarlist

This command will write the tarfile containing all the files in this directory and any subdirectories to the tape. The "rlvwrite" information messages will be written to file "rlout" and the tar verbose output will be written into file "tarlist".

See the examples section below for more tar examples.

11. Writing a tape for export to an IBM system

To create a "transportable" tape with files written in ebcdic code, use the "conv=etext" attribute. This attribute can be specified in the "rlvcreate" command, set using the "rlvedit" command, or specified in the "rlvwrite" command. The "format" attribute should be set to "IBMU" for an unlabeled tape or to "IBM" for a labeled tape.

For an unlabeled tape, the command

rlvwrite  if=diextra.f  fseq=1

will write file "diextra.f" as file 1 on the tape, using the "conv" and "rformat" attributes recorded in the catalog.

When writing labeled tapes, by default REELlibrarian writes four header (HDR) and four trailer (EOF) records. Use the following environment variables to suppress the extra records:

setenv NOHDR3  yes

setenv NOHDR4  yes

setenv NOEOF3  yes

setenv NOEOF4  yes

Use the command

rlvwrite  fseq=1  if=diextra.f  fid=diextra.f

to write to a labeled tape. The keyword "fid" gives the name to include in the header labels.

The "rformat" keyword may be used in the "rlvwrite" command to specify the record and block sizes for the output file. This will supersede the value in the catalog.

See the examples section below for a complete example.

12. Additional notes for writing tapes

The "rlvwrite" command has many keywords. A complete list is in the man pages. The keyword "fseq" may be used to specify the sequence number of the file to be written on the tape. "Fseq" can be used if you make an error and need to repeat the "rlvwrite" command. However, remember that the last write command to a tape defines the end of the tape. You cannot write five files on a tape, then rewrite file 2 and expect to preserve files 3, 4, and 5. The tape will now be ended after file 2. If you do not use "fseq", the default is to write the file following the file most recently accessed.

13. Handling errors

If the actions below do not clear your error, contact the Help Center (831-6000) for assistance. It may be necessary to contact Operations or the NSS systems programmers to clear your tape from an unaccessible state.

• Error message: "Error: End of Volume."
  This message may or may not indicate an error. Check your output file. The message may just be informing you that the end of the tape was reached.

• Error message: "Error: Volume or Volumeset in use elsewhere."
  If you receive the message "Error: Volume or Volumeset in use elsewhere.", use the following command to cancel the mount:
  rlfree

  Error message: "failed", "note: Volume format incorrect", "note: Volume vsn incorrect"
  If your mount fails and you receive the message "failed", your tape does not match the information in the catalog. Use the following procedure:

  	1. Check the tape with the command
  		rlr volset=<volset> vinfo
  	   Look for a note at the bottom of the output.
  	2. If you have the tape mounted, you will have to detach it first
  	   before using the rledit command.  Use 
  		rlvrelease
  	   to detach the tape.
   	3. If the note states "Volume format incorrect", examine the 
  	   "format" and "fingerp" fields. If the value in "fingerp" 
  	   starts with an "I", the tape is labeled.  Use the command
  		rledit format=IBM <vid>
  	   to change the format. 
  	   If the value in the "fingerp" field starts "U", the tape 
  	   is unlabeled.  Use the command
  		rledit format=IBMU <vid>
  	4. If the catalog listing contains the note "Volume vsn incorrect",
  	   the value reported in the "vsn" field is wrong.  You must
  	   set this field to the label recorded on the tape.  The
  	   correct internal label is reported in the field labeled
  	   "fingerp" in the six characters following the leading "I".
  	   Use the command
  		rledit vsn=<correct internal label> <vid>
  	   replacing <correct internal label> and <vid> as appropriate.
  	5. Access the tape again using the "rlvaccess" command.
  	6. If you have difficulty changing the catalog or reaccessing the
  	   tape, try using the command
  		rlvtran <volset>
  	   to reset the catalog.
  

  Error message: "Error: Volumeset contains non-mountable volumes."
  If you receive the message "Volumeset contains non-mountable volumes." in response to the "rlvaccess" command, check the tape using the "rlr" command and examine the "maint" field. If the value of this field is 64, contact the Help Center. Your tape will have to be reset by Operations. If the value of "maint" is 0, use the command

  rlvtran  <volset>
  to reset the catalog.

  Error message: "Error: Un-accessed volume referenced."
  If you receive the message "Un-accessed volume referenced." in response to an "rlvread" command, use the "rlvaccess" command to re-access the tape. It may also be necessary to use the "rlfree" command if the "rlvaccess" command produces an additional error message.

14. Changing catalog information

To change an attribute, use the full-screen interface or the commands:

rlvedit  <keyword=value>  <volset>

rledit  <keyword=value>  <vid>

rlfedit  <keyword=value>  volset=<volset>

The man pages contain complete lists of the keywords and associated values.

A. Setting volumesets for shared access

The <volset> is the volumeset name you specified when you created the tape or the default name of a period followed by the tape reel number. The <vid> is the tape reel number. To share volumesets with another person, the owner must set the access mode of the volumeset. In addition, for volumesets written with REELlibrarian, the owner must set the access mode of each file of the volumeset.

The "vmode" attribute controls access to the volumeset. The default mode of 700 allows the owner full access to the volumeset. To allow someone else to see the catalog information and to mount and read the volumeset, the owner must set the vmode to 755 using the command:

rlvedit  vmode=755  <volset>

To allow someone else to mount and read your volumeset without seeing the catalog information, set the vmode to 744.

The "fmode" attribute controls access to specific files in the volumeset. It is NOT necessary to set the "fmode" for tapes submitted at the I/O Counter or transferred from the UDelVM tape library. The "fmode" needs to be set ONLY for volumesets written with REELlibrarian. The default mode of 700 allows the owner full access to a file. To allow someone else to read a file, set the fmode to 744 using the command:

rlfedit  fseq=<n>  fmode=744  volset=<volset>

replacing <n> by the number of the file. This command must be repeated for each file in the volumeset. To unlock several files, you may set up a loop to invoke the "rlfedit" command. For example, to unlock 15 files:

set i = 1

while ($i <= 15)

rlfedit fseq=$i fmode=744 volset=<volset>

@  i++

end

B. Setting the record size

The attribute "rformat" describes the record size for files in the volumeset. Use the command:

rlvedit rformat=<fmt:blen:rlen>  <volset>

where <fmt:blen:rlen> are replaced by the record format, block length, and record length. Sample values for record format are "fb" for fixed block and "v" for variable length. For example:

rlvedit  rformat=fb:8000:80  .A01023

defines a format of 80 characters per record and 8000 characters per block on volumeset .A01023.

If your tape has several files with different record and block sizes, you may use the "rformat" attribute in the "rlvread" statement as shown in the example section.

C. Automatically converting to ascii

Tapes made on UDelVM and the B7700 will be written in ebcdic character code. To set these tapes so the files are automatically converted to the ascii character code used on the UNIX systems, set the "conv" attribute with the following command:

rledit  conv=etext  <vid>

The value "etext" will convert the data to ascii, remove trailing blanks from each line, and terminate each line with a nl (new line) character. If the tape is labeled, the correct record size is read from the label on each tape file. If the tape is unlabeled, you must also set the "rformat" as described above or specify the value in the "rlvread" command.

If you want to preserve all the blanks in the file and just convert the characters to ascii, use the command:

rledit  conv=edata  <vid>

The output file will be one big block with no line breaks. You can break the file into records using the dd command.

15. Releasing (scratching) a tape

To release (scratch) a volumeset, use the command:

rlvscratch <volset>

The tape is immediately returned to the pool of scratch tapes.

16. Information about UDelVM labeled tapes

If your UDelVM tape is labeled (SL), you must edit the tape catalog information to set the correct format. Use the command:

rledit   format=IBM   <vid>

replacing <vid> with the tape reel number.

A. Tapes with A and C reel numbers

For labeled tapes with reel numbers starting with A or C which were made on the UDelVM system, internal labels will be the same as the vid value. This value is the default value and is listed as "vsn" in the catalog report.

B. Tapes with B reel numbers

For labeled tapes with reel numbers starting with B, internal labels will not be the same as the vid value. You must change the "vsn" value to the label recorded on the tape. Use the command:

rledit  vsn=<internal label>  <vid>

replacing <internal label> and <vid> as appropriate. If you do not know the internal label, use the following two commands to mount the tape:

rlvaccess   <volset>

rlvdisplay   rep=scan

The "rlvdisplay" command will fail, but the "fingerp" field in the catalog information will show the internal label in characters 2-7. See the section "Handling errors" for more information.

17. Complete examples

Following are complete examples, from mount request to detach.

Example 1: Mounting and reading a labeled tape.

Tape C22333 is labeled and contains 6 files. The tape was written on UDelVM and the files are in ebcdic character code. You want to read one file from this tape.

a. Edit the catalog, changing the "format" and "conv" attributes. Check the catalog information:

rledit  format=IBM  conv=etext  C22333

rlr  volset=.C22333  vinfo

or use the full-screen interface via the "rl" command.

b. Request a device for the tape:

rlvaccess  .C22333

c. Scan the tape to find the names of the files and the record and block sizes:

rlvdisplay rep=scan

d. Put the "rlvdisplay" job in the background: suspend the job using ctrl-z (hold down the ctrl key and press z). After the job is stopped, enter

bg

To see the jobs in the background, type

jobs

After the tape is mounted, the output from the "rlvdisplay" command will print on your display screen.

e. Read file 3 from the tape:

rlvread fseq=3 of=FID

The output file is assigned the name recorded in the tape label.

f. Detach the tape:

rlvrelease

Example 2: Read 10 files from a labeled tape.