The HSI interface is one of two primary tools for transferring data to and from HPSS. The other primary tool is the HTAR utility, which is used for transferring large numbers of files. This page provides information on using HSI commands.
Also see HSI Help.
Files that are deleted from or overwritten on HPSS cannot be recovered. To avoid inadvertent data loss, carefully review the section below on Special HSI commands.
HPSS is shared by a large number of users, and there are individual and global limits on file actions that can be executed concurrently. See Use and storage policies for details regarding these limits.
Also see Optimizing HPSS file retrieval. Configuring your requests based on tape location can result in quicker retrievals in some cases.
If you need to perform an operation on 100,000 or more of your HPSS files (with commands such as chacct, chcos, chgrp, chown, cp, mv, and rm, among others), contact the CISL Help Desk or Consulting Services Group for assistance so we can avoid slowing the system for all users.
Review and follow CISL best practices for managing your files and data transfers. They will help you make the most efficient use of your computing and storage allocations.
Some commands—including mv, put, and cp—can overwrite data at their targets. Files deleted from or overwritten on HPSS cannot be recovered, so establish directory permissions carefully to help prevent inadvertently overwriting your HPSS files with these commands.
The cp command also resets a file's project code to your default code, so be especially careful with this if you have multiple projects to which you can charge. If you have files associated with non-default groups, the command will reset the group ID, as well.
Use cput and cget to avoid data loss. While put unconditionally clobbers its target, the conditional cput command will not overwrite a file with the same name. Similarly, using cget rather than get will prevent you from inadvertently overwriting a file on your local drive when retrieving an HPSS file with the same name.
Use put and get only when you know that you want to overwrite existing data.
When fetching files from HPSS (with either get or cget), make sure you have sufficient room in your GLADE file space. If you exceed your GLADE quota, the transfer will fail.
HSI uses common UNIX-like commands that generally work the same way as their UNIX counterparts.
To start HSI after logging in to Yellowstone, just enter hsi on your command line. (To use HSI on NCAR systems that are outside of the Yellowstone environment, see Kerberos and HSI.)
Below are other common commands and examples of how to use them. Click here for a printable quick reference sheet.
This command writes local file file from your current working directory to HPSS as /home/username/file:
[HSI]/home/username-> cput file
To write the file to HPSS with a different name, follow this example:
[HSI]/home/username-> cput file : newfile
Absolute path names for local or HPSS files also are acceptable. The local file always comes before the colon, with both the cput and cget commands.
To put a set of files into a target directory, change to that directory and execute the cput command.
[HSI]/home/username-> cd /home/user/targetdir; cput file-pattern
UNIX users sometimes try to do the following, where targetdir is an existing directory (or a directory that is to be created with the -P option). HSI does not support this:
[HSI]/home/username-> cput file-pattern : /home/user/targetdir
You can specify a source with the -R (recursive) option in HSI, but you cannot specify a target with it. If you try, the command will interpret your source, your target, and the token “:” all as sources. This can produce unexpected and even damaging results.
Correct: The proper way to use this command is to change to the target directory first, then execute your cput command with the -R option. For example, to put the local directory mydir down to an HPSS target directory /home/username/test:
hsi "cd /home/username/test; cput -R mydir"
The result is a directory /home/username/test/mydir that contains all the files and directories from your local mydir directory.
Incorrect: Here’s an example of how this often is done incorrectly by trying to write the source file tree rooted at mydir to /home/username/test/mydir:
hsi cput mydir : /home/username/test/mydir
You will get an error message recognizing that mydir is a directory and telling you that you need to use the -R option. Take care to execute this correctly, as shown above, or you risk overwriting valuable data.
Use cget to retrieve an HPSS file into your current working directory on your local machine:
[HSI]/home/username-> cget filename
To read the HPSS file into your current working directory with a different name, follow this example:
[HSI]/home/username-> cget newname.file : hpss.file
HSI can be invoked in several modes:
If you are working with our HPC, analysis, or visualization systems*, to start an HSI session all you need to do is enter hsi on the command line.
To exit the HSI environment, enter quit.
HSI commands can be entered from the command line, without starting an HSI session first. To do this, you simply type the command like this:
hsi cput xxx : yyy
The command will be executed, then control will return to the shell. This is how you would put HSI commands in a script, or in a “system” call from a running program. Another batch mode option is to create a file containing the desired HSI commands and executing one of the following:
hsi in filename
hsi < filename
Batch (LSF) and cron jobs can use HSI in the same way as the interactive and non-interactive jobs described above. On Yellowstone, use the hpss queue for these jobs.
Here is one example of how to submit a job that will execute a transfer:
bsub -n 1 -q hpss -W 2:00 -P project_code hsi cget mydata