The Digital Cartridge Server Component is a single component of the Automated Cartridge System (ACS). Several thousand tape cartridge volumes housed in one or more Library Storage Modules (LSMs) can be mounted, accessed, and dismounted to and from multiple tape transport devices under full robotic control.
For the purposes of this document, two tape drives are being made available to users. Access to these drives will be by way of a batch queue with a job limit of two. If additional drives are made available in the future, the interface described in this document may be expanded by increasing the job limit of the batch queue.
This document is intended for all users of the Digital Cartridge Server Component interface to the StorageTek 4400 Automated Cartridge System (ACS). Its primary purpose is to provide applications programmers with a standardized mechanism to stage files on tapes controlled by the ACS onto disk and to manage the files on disk.
It is assumed that the reader is familiar with the general capabilities of the Automated Cartridge System and with the Digital Cartridge Server Component for VMS.
It is also assumed that the reader is experienced with the VAX FORTRAN programming language and writing DCL command procedures.
Desirable properties of the DCL interface are:
$ STAGE tape-id [output-logical-name] $ STAGE/COMPLETE=[status]
This qualifier is a required value giving the name of the format of the tape. This will be the name of a procedure developed by SLAC to process the tape identified. The name does not include either a directory specification or file extension.
This qualifier is the internal name of the file on the tape identified. If the tape data format identified by the /FORMAT qualifier does not require a filename, this parameter may be omitted.
This qualifier is the estimated size of the file in Mbytes. If not specified, a default of 200 Mbytes will be used. The upper limit is 600 Mbytes. Note that the file will only be the actual size needed for the file. This value is only needed to see if other files must first be deleted.
This qualifier determines whether the user will wait until the staging is complete. The default for this qualifier is WAIT. If the qualifier is NOWAIT, the output file specification will be written to the user's SYS$OUTPUT and the user will later be notified that the batch job creating the file has completed. If the optional parameter output-logical-name has been specified, the output file specification will have been assigned to this logical name.
$ STAGE/INFILE=MYFILE/FORMAT=FILECOPY/MBYTES=10/NOWAIT XY7890This command will stage the file MYFILE on the tape volume XY7890 to disk using the command procedure identified by FILECOPY. The size of this file is known to be 10 Mbytes. The user does not wait for this to be accomplished and unless the file already exists on disk, a message containing the output specification of the file to be created and information that the job to create the file has been submitted will be sent to the user.
STAGETAPE will first find out if the file currently exists in the staging area. If it does, the name of the file and a successful status will be returned to the caller.
If the file does not currently exist, the staging area is checked to see if the staging area has enough space available to hold the tape. If not enough space exists, files are deleted until space is available. File management will attempt to manage files so that the most recently accessed files will remain in the staging area.
After setting up the parameters, the command procedure is submitted to the tape batch queue. If the NOWAIT option was selected, the name of the output file and a status that the file is in process will be returned to the caller. If the WAIT option was selected, the subroutine will wait until the batch job completes and return the name of the output file and either a successful status or a status showing the error that occurred.
STATUS = STAGETAPE (TAPEID,INFILE,FMT,SIZE,OPTION,
OUTFILE,OUTFILE_LENGTH)
A FORTRAN include file, STAGEDEF.TXT is available for use in FORTRAN programs to define the values of the above condition codes.
$ LINK [main-program],STAGE$EXE:STAGETAPE,NFS__MAP,STAGEMSG
$!
$! FILECOPY.COM - This procedure copies a file from a FILES-11 tape
$! to the staging area
$!
$! A reserve error requires special handling
$ ON ERROR THEN GOTO RESERVE_ERROR
$!
$ CARTRIDGE RESERVE 'P1' 'P2'
$DO_MORE:
$ ON ERROR THEN GOTO OTHER_ERROR
$ CARTRIDGE MOUNT 'P1' 'P2' LOGICAL_DRIVE
$ TAPE_DRIVE = F$TRNLNM("LOGICAL_DRIVE")
$ COPY 'TAPE_DRIVE''P3' 'P4'
$ CARTRIDGE DISMOUNT 'TAPE_DRIVE'
$ SAVE_STATUS = $STATUS
$ GOTO DONE
$RESERVE_ERROR:
$! Wait 5 minutes, try to reserve again
$ WAIT 00:05
$ ON ERROR THEN GOTO RESERVE_ERROR
$ CARTRIDGE RESERVE 'P1' 'P2'
$! Successfully reserved tape, check to see if file is already there
$ IF F$SEARCH('P4') .EQS. "" THEN GOTO DO_MORE
$! Found file, no need to continue
$ GOTO DONE
$OTHER_ERROR:
$ SAVE_STATUS = $STATUS
$ WRITE SYS$OUTPUT F$MESSAGE(STATUS)
$DONE:
$ CARTRIDGE RELEASE 'P1' 'P2'
$ STAGE/COMPLETE='SAVE_STATUS'
$ EXIT SAVE_STATUS