[ PAGE TOP ]

When HSI begins execution, it reads the system-wide startup file: /usr/lib/hsirc and the user's private startup file (if it exists): ~/.hsirc Both of these files are stored in local storage, not in the user's HPSS space.

HSI also will look for a startup file in the user's HPSS home directory after authentication has completed successfully.

Startup files are used to contain startup options for HSI. Input lines in the file consist of comments and directives.

• Comment lines begin with a "#" character.
• Directive lines are of the form:

      option = value
  Note that the spaces surrounding the "=" are required.

  Currently recognized options are:

  • lines = n - sets the lines per page. This is currently unused by HSI, but may be used for listings n the future'
  • columns = n - sets the default line width for listings. Note that HSI tries to determine the screen width by making the appropriate system calls; however, for some terminal types, e.g. xterm, the system sometimes returns a bogus value. Setting this option allows setting the screen to a fixed width.
  • PS1 = "string" - sets prompt string (see below)
  • PS2 = "string" - sets continuation prompt string

  The default prompt string ? can be replaced with a string of the user's choosing. Metacharacters of the form "%x are expanded each time the prompt is displayed. The following metacharacters are currently supported:

  • %C - DCE cell name (DCE version of HSI only)
  • %D - system date, in yyyy/mm/dd format
  • %T - system time, in hh:mm:ss format
  • %N - current command number for the connection
  • %W - current HPSS working directory
  • %w - current local working directory (Note: this has been changed in the upcoming version of HSI (2.4). The new meaning is the same as %W, except that the prompt string will be truncated if it exceeds a user-settable max length).
  • %c - current connection ID (non-DCE HSI only)
  • %h - local hostname
  • %H - DCE Hostname (DCE version) or HPSS server hostname for non-DCE version

For example, to set the default prompt to the current HPSS working directory, followed by the string "->", the following line could be inserted in the .hsirc file:
     PS1 = "%W->"

[ PAGE TOP ]

---

2.4 What is an HSI Request?

An HSI request is your input to HPSS to accomplish a desired function. You sign on to a computer and run the HSI utility program to communicate with HPSS. HSI can be used interactively, but it can also be used in single-line execution mode or called from an executing program or a command-language script (for example, as part of a batch job).

You start HSI by entering

    hsi <return>

After login validation has completed, you will receive any startup messages and the prompt (normally a question mark "? ") indicating that HSI is ready to accept input. (See the PS1 keyword, and the .hsirc startup file for info on changing the prompt string).

You can then enter HSI commands. When you are ready to finish, enter

    quit <return>

(Note that there are aliases for the "quit" command, such as "end", which will all cause HSI to terminate.)

[ PAGE TOP ]

---

2.5 HSI Request Format

The basic format for all HSI requests is
COMMAND parameter KEYWORD=value ...
where

• COMMAND describes the desired action, such as saving or getting a file. The command must be the first word of each request, while parameters and keywords can be in any order. See Chapter 3, HSI Requests, for more information.
• parameter is either the object of the request or an option. It is most often the name of a file that is known to both the local computer and the HPSS, or an option to control execution of the current request. See Parameters and Options in Chapter 3 for more information.
• KEYWORD=value is used to specify additional information in a request. One example would be to specify the directory for a list of files to be accessed (for example, get dir=/foo a b c). See Keywords in Chapter 3 for more information.

HSI returns a response to indicate the success or failure of your request and a prompt for the next input. See Chapter 8, Commands, Keywords, and Parameters, for a complete description of all commands, parameters, and keywords in alphabetical order.

[ PAGE TOP ]

---

2.6 HSI Response Format

HSI returns a response for each request entered. The response shows whether the request was executed successfully or was not completed due to some error. If an error occurred, the response indicates why the request failed.

The basic format of a normal response is

COMMAND PATH DATE TIME

Error conditions can be detected by HSI as the request is interpreted and executed. The basic format of an error response is

***HSInnnn PATH text DATE TIME

where

nnnn = the error code
text = a brief explanation of the error

Refer to Chapter 4, HSI Responses, for more information about responses and to HSI Return Codes for a listing of HSI error responses.

[ PAGE TOP ]

---

2.7 HPSS Tree Structures

HPSS supports a hierarchical storage structure called a tree, which consists of segments called nodes:

• Nodes can be subdirectories, or file descriptors.
• The origin of the tree is called the root.
• Branching out from the root are descendant nodes.
• Descendant nodes can be subdirectories or file descriptors.
• Each root or subdirectory node contains a list of its descendants.

A subdirectory (your home directory) is created for you automatically when you are given an HPSS account. When you use HSI or FTP to login to HPSS, you are automatically placed into this directory to begin your session; you can then store and retrieve files from that directory with simple get or put commands.

A file descriptor node is created when a file is first stored on HPSS. It contains information about the file, such as its size and hierarchy ID, but not the actual file data. File descriptor nodes cannot have descendants.

File trees, when illustrated, are customarily shown as inverted. The root is shown at the top with descendant nodes beneath it. Connecting branches show the relationships between the nodes and the root (see the Simple Tree example). If you need to save only a few files, you can probably use a simple
tree (one with no subdirectories). Complex trees (those with subdirectories) are described in Chapter 5: Tree Structures, Directories and Paths

Note: This tree morphology is similar to that use in most computer file systems, but HPSS differs other file systems in significant ways. For example, some information about files stored in HPSS is stored in a database that is separate from the actual file storage. This makes some operations more efficient, and others more expensive, and represents design choices based on the expected uses of HPSS.

[ PAGE TOP ]

---

2.8 Paths and Working Directories

To store or retrieve a file in an HPSS tree, you may specify to HSI the complete path from the root node to the file node. The name of each node is preceded by a slash (/) and then chained together from the root downward to form the complete path. The maximum length of each node name is 255 characters. The maximum total path length, including slashes, is 1023 characters.

In the simple tree shown in the Simple Tree example, the complete path to the file "Data1" is

/u/tom/Data1

However, you do not have to type in the complete path every time you refer to an HPSS file. "Working Directories" are a set of special variables in which you can store partial or complete paths. The primary Working Directory contains your HPSS home directory as a path when you first start the HSI Interface. If a request contains a path without the leading slash, then HSI forms the complete path by combining

• the path in the primary Working Directory and
• the path that was entered with the request, connecting them with a slash.

The following example shows you how user tom (assuming that /u/tom refers to tom's home directory) could retrieve the file Data1.

Example: using the default Working Directory path name

get Data1

instead of

get /u/tom/Data1

There are nine other Working Directories. Using them is optional and requires planning, but they are helpful when dealing with multiple trees or with requests that require two paths. See Chapter 5, Tree Structures, Directories, and Paths, for more information.

[ PAGE TOP ]

---

2.9 HPSS Security and File Sharing

To execute an HSI command successfully, the user must have access to the affected files or directories as per normal UNIX file systems:

• read permission is required in order to get a file or list a directory
• write permission is required in order to put a file or modify the contents of a directory
• execute permission is required in order to search a directory

HPSS internally uses a number called a User ID, or UID, to identify each user. This number is assigned by the system administrator when you get your account and is used to identify all HPSS nodes which you create.

In addition, you may be placed as a member of one or more administrative groups, each of which is known to HPSS by a Group ID, or GID. When HPSS validates your access rights to files, it takes into account all GIDs of which you are a member. The list of groups to which you belong is also referred to as your group vector.

If you expect to share files with other users, you will need to understand access rights. All files are protected against unauthorized access. You can give other users access through the proper combination of permission bits. See Chapter 6, Security and File Sharing, for more information.

Note: Each NERSC User is assigned to a "Group" within HPSS that is associated with the user's "repository", the accounting entity in which CPU time and storage allocations are maintained. However, special HPSS "Project Groups" are also available for the express purpose of expediting files sharing among specific groups of users, even if they belong to different repositories. A Project Group provides a separate "home" directory, independent from those of the member individuals. Storage usage charges incurred by a Project Group are levied against a specified repository, usually that of the individual who requested its creation. Project Groups require special setup, which is done only on request. To inquire about this, send email to consult@nersc.gov.

HPSS supports ACLs for multilevel security. However, ACL support is not included in HSI at this time.

[ PAGE TOP ]

---

2.10 Interactive Use of HSI

Interactive use of HSI involves the following activities:

• Start HSI on your computer by entering
hsi <RETURN>
• Enter requests using the format defined in Section 3.1, Request Format.
• Verify responses returned from HSI for each request entered.
• Terminate HSI with the end command (or one of its aliases, "quit," "stop," "bye").

The following example illustrates the interactive use of HSI with one request per line. The request is followed by an explanation of the purpose of the request, and then by the response from HPSS. Note that the HSI prompt has been omitted for clarity and that the logged-on user has user name "bugs" with user id "12345".

Example: interactive use of HSI

• Invoke the HPSS Interface utility.
hsi
Username: bugs UID: 12345 CC: 1000 200 Copies: 1 [hsi.2.8 Thu Apr 25 14:49:22 PDT 2002]

• Print the name of the current working directory.
pwd
pwd0: /u/bugs
• Make a subdirectory called Bugsfood, change into it, and save the file carrots.
  Note: The semicolon (";") characters are command separators.
md Bugsfood;cd Bugsfood;s carrots
added /u/bugs/Bugsfood 07/25 13:53
saved test.sh:/007142/Test/Bugsfood/carrots (203 bytes) 07/25 14:01
• Get a condensed, one-line listing for the root and the file just saved.
ls
/u/bugs/Bugsfood:
carrots
• Copy a file to the local computer, but give it a different name locally.
  Note: The spaces surrounding the ":" character are required; this character and its surrounding white space separates the local file specification from the HPSS file specification.
get newcarrots : carrots
get newcarrots:/007142/Test/Bugsfood/carrots (203 bytes written:94/07/25
14:01) 07/25 14:07
• Delete the file just saved.
delete Bugsfood/carrots
deleted /u/bugs/Bugsfood/carrots 07/25 14:12
• Terminate the session.
end

[ PAGE TOP ]

---

2.11 Single-Line Execution

In single-line execution mode (one-liners), the HSI invocation and all the requests are included in one execute line. When a <RETURN> is entered, each request is executed, HSI ends, and control returns to the operating system of the local computer. You can continue request input on a second line with a backslash (\) as the last character of the line, and single-line execution will still be in effect (see Request Format Rules in Section 3.2).

The execute line for single- line execution has the form:

HSI request1; request2; ...

where request1, request2, ..., are HSI requests.

In the following example, the one-liner accomplishes some of the same tasks as the interactive session shown in the previous example. The space following "hsi" and the semicolons between requests are required. Additional spaces are permitted. The command is placed in double quotes to preclude interpretation by a Unix command shell interpreter program.

Example: single-line execution

hsi "cd Bugsfood; s carrots; get newcarrots : carrots; del Bugsfood/carrots"

The example command line

• calls HSI;
• changes to the directory "Bugsfood";
• executes save to store the file "carrots";
• executes get to get the file "carrots" into local file "newcarrots";
• deletes the file "carrots" from directory "Bugsfood"; and
• ends the HSI session.

Note: Commands may often be abbreviated, as in "s" for "save", or shortened, as in "del" for "delete".

[ PAGE TOP ]

---

HSI may also be used in scripts and batch files.

Note: NERSC recommends caution in using HSI in batch scripts, as HPSS delay will stall a parallel job, but the lost time will count against the job's requested runtime.

[ PAGE TOP ]