The following help files are for systems that do not have a TMS interface.
\Filename{H2vaxuser-EINIT}
\section{EINIT}
1 \Rind{EINIT}
Use the EINIT command to write a magnetic tape label encoded in EBCDIC.
Format:
RUN SETUP_EXE:EINIT
The volume to be labelled must already be mounted /FOREIGN/WRITE on
the tape unit with logical name INTAPE.
The utility will prompt for the volume label to be written.
\Filename{H2vaxuser-LABELDUMP}
\section{LABELDUMP}
1 \Rind{LABELDUMP}
Use the LABELDUMP command to find out the magnetically recorded label
(if any) of a magnetic tape.
Format:
LABELDUMP [(visual identifier)]
2 Parameters
(visual identifier)
Specifies the number of the tape on the tape reel itself.
If you do not specify this parameter, you are prompted for it.
2 Qualifiers
/GENERIC
/GENERIC=TA90 (D)
Use this qualifier to instruct LABELDUMP to allocate a certain
device type. If not specified, the generic device will default to
TA90 - the IBM 3480 compatible drive.
The generic devices available on your system are defined by the system
manager as logical names. For example, the logical name for TA90 drives
is SETUP_TA90S. The following table gives some examples.
Generic Device type Characteristics Logical name
=================== =============== ============
TA90 (or 3480) 3480 cartridge SETUP_TA90S (or SETUP_3480S)
TA78 6250 bpi 9 track SETUP_TA78S
TK50 TK50 cartridge SETUP_TK50S
/DEBUG
This qualifer requires SYSPRV and is primarily of use for debugging
new versions of the LABELDUMP command. If specified, extra debug information
will be displayed during command processing.
/WAIT
/WAIT (Default in BATCH)
/NOWAIT (Default otherwise)
This parameter controls whether LABELDUMP will exit if all tape drives
are currently in use, or wait until one becomes free. If executing
in BATCH mode, /WAIT is in effect unless explicitly negated.
2 Examples
LABELDUMP XIN101
Dumps the label of XIN tape XIN101.
\Filename{H2vaxuser-SETUP}
\section{SETUP}
1 \Rind{SETUP}
The SETUP command should always be used to mount magnetic tapes,
rather than the standard VMS MOUNT command.
SETUP command will ALLOCATE a tape drive, MOUNT the tape
and perform volume-label checking. The tape is then re-mounted via a
standard VMS mount command and made available for user-processing.
In addition to the qualifiers presented below, any MOUNT qualifers
may be used. See HELP MOUNT for further information on additional
qualifiers.
Format:
SETUP [(volume-label|VSN)] [(visual-identifier|VID)] [(logical-name)]
2 Parameters
(volume-label|VSN)
Specifies the MAGNETICALLY recorded label on the volume.
Labels can have from 1 through 6 characters. This is the
equivalent of the IBM MVS volume serial name (VSN) on the DD statement.
The volume-label parameter is always required. If your tape is unlabelled,
specify the same value as the visual-identifier.
N.B. if the VSN is in lower or mixed case, it must be enclosed in
double quotes.
(visual-identifier|VID)
Specifies the contents of the sticky label on the volume reel itself.
VID's must be exactly 6 characters.
The visual-identifier must be a CERN tape number (5 digits followed
be a check letter), an experimental tape number, (1 or 2 characters
followed by 5 or 4 digits) or an XIN/XUT number.
XIN tapes are read only.
The visual-identifier parameter is always required.
logical-name[:]
Defines a 1- through 63-alphanumeric character string logical
name to be associated with the device allocated.
The logical name must be used to reference the drive on which the
tape is mounted.
If you do not specify a logical name, the SETUP command assigns
the default logical name TAPE$volume-label.
2 Qualifiers
/BACKUP
If you specify /BACKUP, your tape will be mounted /FOREIGN, after
SETUP has verified that the correct volume-label has been specified.
Use this qualifier to read and write tapes in BACKUP format, in
addition to the relevant /LABEL qualifier.
/DEBUG
This qualifer requires SYSPRV and is primarily of use for debugging
new versions of the SETUP command. If specified, extra debug information
will be displayed during command processing.
/FOREIGN
Use of this qualifier requires VOLPRO or BYPASS privilege.
Without privilege, tapes may only be mounted /FOREIGN if the
/BACKUP qualifier is specified, together with the correct
/LABEL qualifier and value. See the description of the /BACKUP
and /LABEL qualifiers and the examples section for more details.
If you do not know the magnetic label of a tape, use the LABELDUMP
command to determine it.
/GENERIC
/GENERIC=TA90 (D)
Use this qualifier to instruct SETUP to allocate a certain
device type. If not specified, the generic device will default to
TA90 - the IBM 3480 compatible drive.
The generic devices available on your system are defined by the system
manager as logical names. For example, the logical name for TA90 drives
is SETUP_TA90S. The following table gives some examples.
Generic Device type Characteristics Logical name
=================== =============== ============
TA90 (or 3480) 3480 cartridge SETUP_TA90S (or SETUP_3480S)
TA78 6250 bpi 9 track SETUP_TA78S
TK50 TK50 cartridge SETUP_TK50S
N.B. if /GENERIC is NOT specified and SETUP has been installed with
the TMS option, SETUP will obtain the correct device information from
the TMS.
/LABEL
/LABEL=ASCII (D)
/LABEL=EBCDIC
/LABEL=NONE
/NOLABEL
Indicates, for tape volumes, whether the tape contains VAX/VMS
ANSI labels. Note that /NOLABEL is equivalent to /LABEL=NONE.
You should specify /LABEL=EBCDIC if you wish to read IBM SL tapes.
However, data set positioning and translation must be performed by
the user as the tape is positioned at beginning of tape by SETUP.
To skip files, you may use the DCL command SET MAGTAPE/SKIP=FILES:n.
Note that for labelled tapes the physical file number equals the
logical file number times three minus one. See the EXAMPLES section
for an example.
/WAIT
/WAIT (Default in BATCH)
/NOWAIT (Default otherwise)
This parameter controls whether SETUP will exit if all tape drives
are currently in use, or wait until one becomes free. If executing
in BATCH mode, /WAIT is in effect unless explicitly negated.
/WRITE
/WRITE
/NOWRITE (D)
Controls whether the volume can be written. /NOWRITE is
equivalent to write-locking the device.
2 Mounting_FOREIGN_tapes
On the CERN Computer Centre VAXcluster,tapes do not normally need
to be mounted /FOREIGN. The exception is for processing with BACKUP.
To mount a tape for processing by BACKUP (or any other program that
requires the tape to be mounted /FOREIGN), use
SETUP/BACKUP.
Note that you MUST specify the correct volume-label, if any.
If you want to MOUNT an UNLABELLED tape, use SETUP/NOLABEL.
If you want to MOUNT an IBM tape (i.e. LABELLED in EBCDIC),
use SETUP/LABEL=EBCDIC.
2 Examples
Setup a tape with labels encoded in ASCII.
$ .....
$ SETUP MX1015 MX1015 ! If the SETUP fails, the job will exit.
$ ASSIGN TAPE$MX1015 FOR001
$ RUN DSTANAL
$ EXIT
Setup a tape with labels encoded in EBCDIC.
$ ON ERROR THEN GOTO ABEND ! Protect against problems with SETUP etc.
$ SETUP/NOWRITE/LABEL=EBCDIC 939927 XIN112 MYDRIVE
$ ASSIGN MYDRIVE: FOR001 ! Processing of data sets is up to user.
$ RUN PROG
$ EXIT
$ !
$ABEND:
$ WRITE SYS$OUTPUT "Program abended"
$ EXIT
Mount an unlabelled tape
$ SETUP/NOLABEL XIN101 XIN101 ! Only if the tape is really unlabelled
$ ! will access to the tape be granted.
$ ASSIGN TAPE$XIN101 FOR010
$ RUN MYPROG
$ EXIT
Mount a labelled tape for writing to with BACKUP.
$SETUP/WRITE/BACKUP MICRO PR9902
Mount a tape written on a data acquisition VAX
with EBCDIC labels, blocksize = 3600 bytes and recordsize = 3600 bytes.
$SETUP/LABEL=EBCDIC/BLOCK=3600/RECORD=3600 MC1009 MC1009
$! Skip past volume label to logical file 1
$SET MAGTAPE/SKIP=FILES:1 TAPE$MC1009
$RUN MYPROG ! Uses EPIO, reading from unit 1.
\Filename{H2vaxuser-STAGE}
\section{STAGE}
1 \Rind{STAGE}
Use the STAGE command to perform input or output staging of tape
data, clear existing staged data or query the status of staged
data.
Each group must be explicitly enabled to use tape staging. If you
find that your group is not enabled, please contact the UCO.
2 Command_Syntax
The syntax of the STAGE command is essentially that of SETUP, with some
extensions. Only these extensions are described below.
The format of the STAGE command is:
STAGE [(volume-label|VSN)] [(visual-identifier|VID)] [(logical-name)] -
/NAME=fn/NUMBER=n
3 Parameters
(volume-label|VSN)
Specifies the MAGNETICALLY recorded label on the volume.
Labels can have from 1 through 6 characters. This is the
equivalent of the IBM MVS volume serial name (VSN) on the DD statement.
The volume-label parameter is always required. If your tape is unlabelled,
specify the same value as the visual-identifier.
(visual-identifier|VID)
Specifies the contents of the sticky label on the volume reel itself.
VID's must be exactly 6 characters.
The visual-identifier must be a CERN tape number (5 digits followed
be a check letter), an experimental tape number, (1 or 2 characters
followed by 5 or 4 digits) or an XIN/XUT number.
XIN tapes are read only.
The visual-identifier parameter is always required.
logical-name[:]
Defines a 1- through 63-alphanumeric character string logical
name to be associated with the staged data.
The logical name must be used to reference the staged tape data.
If you do not specify a logical name, the STAGE command assigns
the default logical name STAGE$volume-label.
The logical name is entered into the JOB logical name table, so that
STAGE may be called from a program using LIB$SPAWN. Once the sub-process
has completed, the parent process may then access the staged data via
this logical name.
3 /APPEND
This qualifier invokes output tape staging. Any existing data
is read from the corresponding tape file, before control is
returned to the user. This file must be opened by the user
with the APPEND attribute.
3 /BLOCKSIZE
Use the /BLOCKSIZE to indicate the blocksize of the tape file.
If not specified, STAGE uses a default of 32256 bytes, unless the tape is
labelled, in which case it reads the blocksize from the tape label.
3 /DIRECT
Use the /DIRECT qualifier if you wish to read or write directly to tape.
STAGE will perform the tape mount and file positioning.
3 /NAME=name
Use the /NAME qualifier to indicate the name of file that you wish
to stage. The filename need not be specified for unlabelled tapes. For
labelled tapes, the filename must match that recorded in the tape label.
3 /NUMBER=number
Use the /NUMBER qualifier to indicate the file sequence number that
you wish to stage. If not specified, the first file is staged. STAGE
understands tape labels and does not consider these as data files.
3 /FIXED
Use the /FIXED qualifier to request that the resultant disk file should
have fixed length records. If not specified, the format of the input tape
file is used, if the tape is labelled.
3 /GENERIC=device-type
/GENERIC=TA90 (D)
Use this qualifier to instruct STAGE to allocate a certain
device type. If not specified, the generic device will default to
TA90 - the IBM 3480 compatible drive.
The generic devices available on your system are defined by the system
manager as logical names. For example, the logical name for TA90 drives
is SETUP_TA90S. The following table gives some examples.
Generic Device type Characteristics Logical name
=================== =============== ============
TA90 (or 3480) 3480 cartridge SETUP_TA90S (or SETUP_3480S)
TA78 6250 bpi 9 track SETUP_TA78S
TK50 TK50 cartridge SETUP_TK50S
N.B. if /GENERIC is NOT specified and STAGE has been installed with
the TMS option, STAGE will obtain the correct device information from
the TMS.
3 /IN
Use this qualifier to request input tape staging. This qualifier is
the default stage option, if none of the other options (e.g. /WRITE,
/LIST,/QUERY) is specified.
3 /KEEP
Use this qualifier in conjunction with the /WRITE qualifier to preserve
your data on disk after explicitly writing it to tape. Once the data
has been written to tape, the staged data is treated as if it had
just been input-staged and will eventually be deleted by the staging
system.
3 /NOPRESTAGE
This qualifier invokes output tape staging and is equivalent to a STAGE/APPEND,
except that no prestage of existing data from tape to disk is performed.
In addition, STAGE will not check the output tape. It may only be
used after a STAGE/OUT command, and when some data has already
been written to disk.
3 /NREAD=n
Use the /NREAD qualifier to request how many tape records be read.
If not specified, 20 Megabytes will be staged. You cannot specify
both /NREAD and /SIZE.
3 /OUT
This qualifier invokes output tape staging.
If this qualifier is specified, no pre-stage of existing data
is performed. However, the output tape is mounted to ensure that
it exists and has the correct VOL1 label.
3 /RECORDSIZE=n
Use the /RECORDSIZE parameter to indicate the recordsize of the tape file.
If not specified, STAGE uses a default of 32256 bytes, unless the tape is
labelled, in which case it reads the recordsize from the tape label.
3 /REPLACE
Use the /REPLACE qualifier to request that existing staged data be replaced
by re-reading the input tape. Data is normally only re-staged if more data
is required, or if the disk file no longer exists.
3 /SIZE=n
Use the /SIZE qualifier to request that 'n' Megabytes be staged from tape.
If not specified, 20 MB will be staged.
If /SIZE=0 is specified, the complete tape file will be copied to disk.
If any data already resides on disk, the STAGE operation will not be
performed. To force STAGE to replace an existing file with a complete
new file, use /SIZE=0 with the /REPLACE qualifier.
3 /VARIABLE
Use the /VARIABLE qualifier to request that the output disk file have
variable length records. If not specified, STAGE will use the input record
format, if the tape is labelled.
3 /WRITE
This qualifier is valid only for output tape staging.
Once you have finished writing data to your file, you may request that
the data is immediately copied to tape by use of the /WRITE qualifier.
Use of the /WRITE qualifier is encouraged, to optimize use of the
staging disk. If STAGE is not reinvoked with the /WRITE qualifier,
the data will be moved to tape when disk space becomes low.
3 Examples
VXCRNB stage/generic=rv20/name=test.bck jds001 jds001
%STAGE-I-TAPEINFO, file 1 from tape JDS001 (VSN JDS001), label type ASCII , file
%STAGE-I-FILENAME, corresponding disk filename is JDS001.1.ASCII.JDS001
%STAGE-I-DEFSIZE, 20 Megabytes will be staged by default
%STAGE-I-FILEFND, file already on disk, size = 17892 blocks
%STAGE-I-LARGER, more data is requested that currently resides on disk
%STAGE-I-STGREQ, a stage operation is required
%SETUP-I-PENDING, your tape request is being processed, please wait
%SETUP-I-ALLOC, _VXCRNB$MUA0: allocated
%SETUP-I-ASCII, tape JDS001 contains labels encoded in ASCII
%STAGE-I-STAGING, starting stage of data from tape to disk
%STAGE-I-EOF, EOF on input after 9160704 bytes
%STAGE-I-LOGNAME, logical name for your staged file is STAGE$JDS001
2 Input_Staging
Use the STAGE command to initiate input tape staging of a single tape file.
As input staging is the default, you do not need to specify any qualifiers
to indicate that input staging is required. Note that, if the requested
file is currently being output staged, STAGE will not permit you access.
STAGE uses SETUP routines if a tape mount is required. See HELP SETUP for
details of the SETUP command.
2 Output_staging
Output staging may be requested by use of the /APPEND or /OUT qualifiers.
It is otherwise identical to the input STAGE command.
See the section Command_Syntax for full details on qualifiers.
The /APPEND and /OUT qualifiers will cause STAGE to check that your
output tape exists, and then create a file of the desired size and format.
STAGE assigns a logical name to the disk file, by which you should reference
the file.
If the file already exists on tape, STAGE is able to obtain the format
from the tape label. If not, you must specify the format with the
appropriate qualifiers.
2 Managing_staged_data
The preferred method of managing your staged data is through the STAGE/LIST
command. This permits you to perform other STAGE functions, such as QUERY
or CLEAR commands, without having to specify the full name of the staged
data file.
2 /CLEAR tape(s)
Use the /CLEAR qualifier to delete existing staged data when
it is no longer required. You may only clear data that has been
staged by your UIC group. See HELP STAGE NAMING_CONVENTION for
details of how to specify the name of the tapes to be cleared.
See also HELP STAGE/LIST for a more user-friendly interface to
STAGE/CLEAR.
An alternative method of delete STAGEd data from DCL, or from within
a program is to use the logical name assigned to your data.
3 Examples
The following example shows how data may be deleted using the logical
name assigned by STAGE.
$STAGE/NAME=TEST.DAT XQ1170 XIN130 ! Stage data
... Process data ...
$!Finished with this data - delete it
$DELETE STAGE$XIN130
3 Parameters
4 Tape(s)
The only parameter that is normally required for the /CLEAR function
is the tape, or list of tapes, that you wish to clear.
See HELP STAGE NAMING_CONVENTION for details of how to specify
the name of the tapes to be cleared.
4 /OUT
If the tape that you wish to clear is currently being staged out,
you must specify /OUT. This will clear the file without writing
any data to tape.
2 /LIST
Use this qualifier by itself to invoke a FILELIST like interface to help
you manage your staged data.
2 Naming_Convention
A tape is uniquely identified by is magnetic label (VSN),
label on the tape reel (VID), filenumber and label type. For the
/CLEAR subcommand, you must use the format VSN_VID.FILENUMBER_LABELTYPE
to indicate which tapes are to be cleared. Trailing items are defaulted,
thus JDS001 defaults to JDS001_JDS001.1_ASCII
3 Examples
To indicate a tape with VSN NC0383, VID XIN127, filenumber 3 and labeltype
of EBCDIC, use the format NC0383_XIN127.3_EBCDIC
2 /QUERY
Use the /QUERY qualifier to find out if a given group is enabled for
tape staging, to list which groups are enabled, or query the status
of one or more tapes.
See also HELP STAGE/LIST for a more user-friendly interface to
STAGE/QUERY.
3 /GROUP=list
Use the /GROUP qualifier to indicate which UIC groups you wish to
query. STAGE will indicate whether each of the groups listed may or
may not using the STAGING facility, and which tapes are staged for
each group. The name of each tape is followed by a /I or /O to indicate
whether the tape is being staged in or out.
3 /GROUPS
Use the /GROUPS qualifier to indicate which UIC groups are enabled
for tape staging.
3 /LIST
Use the /LIST qualifier to invoke a FILELIST interface to manage
your staged tape files.
3 /TAPES=list
Use the /TAPES qualifier to query the status of one or more tapes.
STAGE will indicate whether the tapes have been staged, or are in
the process of being staged. If the tapes are currently being staged,
more detailed information, such as 'waiting for tape mount', is also
displayed. The name of each tape is followed by a /I or /O to indicate
whether the tape is being staged in or out.
2 Calling STAGE from FORTRAN
STAGE may be called from FORTRAN, or any other language, using
the VAX/VMS Run-time library routines. For example, a program
may wish to input stage some data, process it, and delete the file.
This it could be by
a) Call LIB$SPAWN to issue the STAGE command, specifying that the
parent process hibernates until the subprocess completes.
b) Once the subprocess has completed, the data will have been staged to
disk, unless a error code is returned.
c) The program can then continue to process this data.
d) Once processing has completed, it can delete the staged file using
LIB$DELETE_FILE, using the logical name returned by STAGE.
integer status
status = lib$spawn('$STAGE/NAME=TEST.DAT XQ1170 XIN132 /SIZE=10')
if (.not. status) call lib$signal(%val(status))
*
* Process data
*
*
* Delete file
*
status = lib$delete_file('STAGE$XIN132')
if (.not. status) call lib$signal(%val(status))
end
\Filename{H2vaxuser-TAPECOPY}
\section{TAPECOPY}
1 \Rind{TAPECOPY}
Use this command to initiate a complete tape to tape copy,
including tape labels, if any.
This command takes no qualifiers - all required information
is prompted for.
As well as copying one tape to another, this command can be
used to copy from 6250 bpi tapes to 3480 cartridges and so
on, by specifying the correct input and output device types.
2 Examples
The example below shows how to copy an input tape to an output 3480
cartridge. The job is executed in batch.
VXCRNA? tapecopy
Command file to copy an entire input tape (including tape labels, if any)
to an output tape.
As well as performing a tape to tape copy, this command file allows you
to copy a 6250 bpi tape to a 3480 cartridge etc, by correctly specifying
the input and output devices required.
If you do not know the tape labels of either input or output tapes, use the
LABELDUMP command to find them, prior to running this command file.
VID of input tape xin103
VSN of input tape (CR=unlabelled) xy0315
Labeltype of input tape (ASCII/EBCDIC/NONE) ascii
Valid devices are:
TA78 (for normal 6250/1600 bpi tapes)
A480 (for IBM 3480-style cartridges)
Input device type (Return=TA78)
VID of output tape cut215
VSN of output tape (CR=unlabelled)
Output device type (Return=TA78) a480
Run in BATCH (Return=NO) y
Job COPY_XIN103_TO_CUT215 (queue CLU$TAPES, entry 43) started on VXCRNA_SYS$TAPE
\Filename{H2vaxuser-WRTAPE}
\section{WRTAPE}
1 \Rind{WRTAPE}
Use the WRTAPE command to copy a disk file to tape, writing EBCDIC
or ASCII tape labels.
WRTAPE is essentially the same as STAGE/OUT except that it allows any
existing file to be specified, using the /INFILE qualifier.
For all other qualifiers, see the description of the STAGE /OUTPUT command.
2 Examples
WRTAPE/INFILE=MYDATA.DAT JDS001 CUT123 /GENERIC=TA90 /NAME=DELPHI/NUMBER=3
The above command writes file MYDATA.DAT to file 3 of the tape with VID CUT123.
The file name to be written on the tape is DELPHI.
\Filename{H2vaxuser-XTAPE}
\section{XTAPE}
1 \Rind{XTAPE}
Use the XTAPE command to examine the labels of a tape and optionally
dump blocks from the specified number of files.
Format:
XTAPE [(visual identifier)]
2 Parameters
(visual identifier)
Specifies the number of the tape on the tape reel itself.
If you do not specify this parameter, you are prompted for it.
2 Qualifiers
/BLOCKS
/BLOCKS=1 (D)
Use this qualifier to specify how many blocks from each file are to be
dumped.
/FILES
/FILES=1 (D)
Use this qualifier to specify how many files are to be dumped.
/GENERIC
/GENERIC=TA90 (D)
N.B. if XDUMP has been installed with the TMS option,
as is the case on VXCERN, XDUMP will obtain the correct
device information from the TMS and /GENERIC should NOT be specified.
Use this qualifier to instruct XDUMP to allocate a certain
device type. If not specified, the generic device will default to
TA90 - the IBM 3480 compatible drive.
The generic devices available on your system are defined by the system
manager as logical names, e.g. SETUP_TA90S, SETUP_TA78S.
/DEBUG
This qualifer requires SYSPRV and is primarily of use for debugging
new versions of the XTAPE command. If specified, extra debug information
will be displayed during command processing.
/WAIT
/WAIT (Default in BATCH)
/NOWAIT (Default otherwise)
This parameter controls whether LABELDUMP will exit if all tape drives
are currently in use, or wait until one becomes free. If executing
in BATCH mode, /WAIT is in effect unless explicitly negated.