1 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 /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