1. Introduction

This section will describe how to manually archive and retrieve files on the local machine using the TSM Command Line Interface (CLI). The screen shots and descriptions that follow refer to a TSM client running on Solaris v5.8 and Windows ME but with the exception of the file specifications the syntax is generic to all platforms.

It should be noted that the CLI is the only interface available to TSM clients running on Netware.

2. Starting the TSM Command Line client

Unix users can start the TSM Archive CLI by running dsmc -se=ox_hfs from the shell prompt.

Windows users can start the TSM CLI by opening a DOS Window from the Desktop and typing the following:

   cd "C:\Program Files\tivoli\tsm\baclient"
   dsmc -optfile=dsm.opt.ARCHIVE

Users will see a prompt similar to below:

Tivoli Storage Manager 
*** Fixtest, Please see README file for more information *** 
Command Line Backup Client Interface - Version 4, Release 2, Level 1.28  
(C) Copyright IBM Corporation, 1990, 2001, All Rights Reserved.

  tsm>

3. Accessing Help

Online help for TSM commands, options and error messages is available by typing help at the tsm> prompt. A menu list of commands and options will display.

4. Querying the server

On starting the TSM CLI, no information about your current configuration settings or filestore is displayed. The following query commands illustrate typical command syntax and output.

4.1. Querying what files have been archived

The syntax for querying what files you have archived involves giving a file specification which is necessarily OS specific. Also, if an incorrect file specification is given it may appear that you have no archived files. Consequently, several worked examples are displayed below for both Windows and Unix environments.

** Unix **

  tsm> q ar /scratch/test1/ 
       Size  Archive Date - Time    File - Expires on - Description
       ----  -------------------    -------------------------------
  2,411,227  28-06-2002 10:51:36    /scratch/test1/j1.jpg Never project 01.1 28/06/2002
    760,632  28-06-2002 10:51:37    /scratch/test1/j2.jpg Never project 01.1 28/06/2002
      3,657  28-06-2002 10:51:37    /scratch/test1/join_actlog Never project 01.1 28/06/2002
    189,282  28-06-2002 10:51:37    /scratch/test1/j-hat.JPG Never project 01.1 28/06/2002
    229,080  28-06-2002 10:51:37    /scratch/test1/j-sidecar.JPG Never project 01.1 28/06/2002

  tsm> q ar /scratch
ANS1083E No files have previously been archived for '/scratch'

  tsm> q ar /scratch/        
       Size  Archive Date - Time    File - Expires on - Description
       ----  -------------------    -------------------------------
      1,536  28-06-2002 10:51:36    /scratch/test1 Never project 01.1 28/06/2002

  tsm> q ar /scratch/ -su=yes
       Size  Archive Date - Time    File - Expires on - Description
       ----  -------------------    -------------------------------
  2,411,227  28-06-2002 10:51:36    /scratch/test1/j1.jpg Never project 01.1 28/06/2002
    760,632  28-06-2002 10:51:37    /scratch/test1/j2.jpg Never project 01.1 28/06/2002
      3,657  28-06-2002 10:51:37    /scratch/test1/join_actlog Never project 01.1 28/06/2002
    189,282  28-06-2002 10:51:37    /scratch/test1/j-hat.JPG Never project 01.1 28/06/2002
    229,080  28-06-2002 10:51:37    /scratch/test1/j-sidecar.JPG Never project 01.1 28/06/2002

** Win ** 

  tsm> q ar c:  
ANS1083E No files have previously been archived for 'C:'

  tsm> q ar "C:\My Documents\"
       Size  Archive Date - Time    File - Expires on - Description
       ----  -------------------    -------------------------------
          0  26-04-2002 14:33:27    \\cles.oucs\c$\My Documents Never test jpgs
          0  26-04-2002 14:33:32    \\cles.oucs\c$\My Documents Never test jpgs

  tsm> q ar "C:\My Documents\*"
       Size  Archive Date - Time    File - Expires on - Description
       ----  -------------------    -------------------------------
          0  26-04-2002 14:33:27    \\cles.oucs\c$\My Documents Never test jpgs
          0  26-04-2002 14:33:32    \\cles.oucs\c$\My Documents Never test jpgs

  tsm> q ar "C:\My Documents\Mac"
       Size  Archive Date - Time    File - Expires on - Description
       ----  -------------------    -------------------------------
          0  26-04-2002 14:33:27    \\cles.oucs\c$\My Documents\Mac Never test jpgs

  tsm> q ar "C:\My Documents\Mac\"
       Size  Archive Date - Time    File - Expires on - Description
       ----  -------------------    -------------------------------
          0  26-04-2002 14:33:27    \\cles.oucs\c$\My Documents\Mac Never test jpgs
    786,021  26-04-2002 14:33:27    \\cles.oucs\c$\My Documents\Mac\macjpgs.zip Never test jpgs
    755,690  26-04-2002 14:33:27    \\cles.oucs\c$\My Documents\win\macpcts.zip Never test jpgs


  tsm> q ar "C:\My Documents\" -su=yes
       Size  Archive Date - Time    File - Expires on - Description
       ----  -------------------    -------------------------------
    786,021  26-04-2002 14:33:27    \\cles.oucs\c$\My Documents\Mac\macjpgs.zip Never test jpgs
    755,690  26-04-2002 14:33:27    \\cles.oucs\c$\My Documents\win\macpcts.zip Never test jpgs
     38,284  26-04-2002 14:33:32    \\cles.oucs\c$\My Documents\win\wzip00.jpg Never test jpgs
     44,041  26-04-2002 14:33:32    \\cles.oucs\c$\My Documents\win\wzip01.jpg Never test jpgs

Note that you need to terminate a directory path with a trailing slash "/" (Unix) or "\" (Windows) in order to get a list of files archived in that folder. If you omit the trailing slash, then TSM will return just the names of directories in that path archived. If you add a wildcard star to the end of a path, TSM will return those files and directories archived immediately below the path given in the query.

Essentially, to get a full listing of all files archived under a top-level directory, terminate the path with a trailing slash and add the -su=yes which is shortform for subdir=yes and allows the query to recursively search for archived files from all subdirectories under the path.

Note that on both Windows and Unix platforms, path names with spaces need to be fully enclosed in quotes. Note also that the Windows client lists the directory in UNC format. This format can also be used for the file specification in the query.

5. Archiving your data

5.1. Archiving selected files

The basic syntax for archiving selected files is dsmc archive /path/to/file(s) -desc="your description here". Thus you can archive a single file:

  tsm> ar /scratch/test1/j1.jpg -desc="First version"

where ar is an abbreviation for archive. Or you can archive multiple files, up to a maximum of 20, on the same command line:

  tsm> ar j1.jpg  h70.jpg  m80.tiff -desc="Second temp version"

More conveniently, or where you wish to batch archive more than 20 files, you can use the -filelist= option to specify a file whose contents are a full pathname to one file on each line, as below:

  cat archlist.020629
/scratch/test1/j1.jpg
/scratch/test1/j2.jpg
/scratch/test1/h70.jpg
/scratch/test1/m80.tiff
/scratch/test1/m90.jpg
/scratch/test1/k90.tiff

  tsm> ar -filelist=./archlist.020629  -desc="In progress version - 29 June 2002"

When repeatedly archiving selected files the importance of using the -description= option becomes clear. The example below shows the output of an q ar /scratch/test1/j* query where no description has been entered and the default has therefore been applied.

       Size  Archive Date - Time    File - Expires on - Description
       ----  -------------------    -------------------------------
  2,411,227  28-06-2002 10:51:37    /scratch/test1/j1.jpg Never Archive Date: 28-06-2002
  2,411,227  30-06-2002 15:07:24    /scratch/test1/j1.jpg Never Archive Date: 30-06-2002
  2,411,227  01-07-2002 12:01:06    /scratch/test1/j1.jpg Never Archive Date: 01-07-2002
  2,411,227  01-07-2002 12:01:06    /scratch/test1/j1.jpg Never Archive Date: 01-07-2002
    760,632  28-06-2002 10:51:37    /scratch/test1/j2.jpg Never Archive Date: 28-06-2002
    760,632  28-06-2002 16:46:03    /scratch/test1/j2.jpg Never Archive Date: 28-06-2002
    760,632  28-06-2002 17:18:54    /scratch/test1/j2.jpg Never Archive Date: 28-06-2002
    760,632  28-06-2002 17:22:28    /scratch/test1/j2.jpg Never Archive Date: 28-06-2002
    760,632  01-07-2002 12:01:06    /scratch/test1/j2.jpg Never Archive Date: 01-07-2002

Using the -description= option can make querying of your archive store much clearer, as below.

       Size  Archive Date - Time    File - Expires on - Description
       ----  -------------------    -------------------------------
  2,411,227  28-06-2002 10:51:37    /scratch/test1/j1.jpg Never Jenkins 1st Initial Scan
  2,411,227  30-06-2002 15:07:24    /scratch/test1/j1.jpg Never Jenkins 1st - 1st amend
  2,411,227  01-07-2002 12:01:06    /scratch/test1/j1.jpg Never Jenkins 1st - 2nd amend
  2,411,227  01-07-2002 12:01:06    /scratch/test1/j1.jpg Never Jenkins 1st Final Version
    760,632  28-06-2002 10:51:37    /scratch/test1/j2.jpg Never Jenkins 2nd Initial Scan
    760,632  28-06-2002 16:46:03    /scratch/test1/j2.jpg Never Jenkins 2nd - 1st amend
    760,632  28-06-2002 17:18:54    /scratch/test1/j2.jpg Never Jenkins 2nd - 2nd amend
    760,632  28-06-2002 17:22:28    /scratch/test1/j2.jpg Never Jenkins 2nd - 3rd amend
    760,632  01-07-2002 12:01:06    /scratch/test1/j2.jpg Never Jenkins 2nd Final Version

5.2. Archiving multiple files and directories

As with the syntax for querying the archive server, there are subtle differences in the interpretation of similar-looking filepaths. For example, the first command listed below will just archive the directory folder and not the files contained therein.

  tsm> ar "C:\My Documents\html-docs\Mac"

  Archive function invoked.

  Directory-->            0 \\cles.oucs\c$\My Documents\html-docs\Mac [sent]
  Archive processing of '\\cles.oucs\c$\My Documents\html-docs\MAC' finished
  without failure.

  Total number of objects inspected:        2
  Total number of objects archived:         1
  Total number of objects updated:          0
  Total number of objects rebound:          0
  Total number of objects deleted:          0
  Total number of objects expired:          0
  Total number of objects failed:           0
  Total number of bytes transferred:        0  B
  Data transfer time:                    0.00 sec
  Network data transfer rate:            0.00 KB/sec
  Aggregate data transfer rate:          0.00 KB/sec
  Objects compressed by:                    0%
  Elapsed processing time:           00:00:03

To archive a directory and it's immediate contents, add a terminating slash "/" (windows), "\" (Unix) to the file path.

  tsm> ar "C:\My Documents\html-docs\Mac\"
  Archive function invoked.

  Directory-->            0 \\cles.oucs\c$\My Documents\html-docs\Mac [Sent]
  Normal File-->    786,021 \\cles.oucs\c$\My Documents\html-docs\Mac\macjpgs.zip [Sent]
  Normal File-->    755,690 \\cles.oucs\c$\My Documents\html-docs\Mac\macpcts.zip [Sent]
  Archive processing of '\\cles.oucs\c$\My Documents\html-docs\Mac\*' finished
  without failure.

  Total number of objects inspected:        4
  Total number of objects archived:         3
  Total number of objects updated:          0
  Total number of objects rebound:          0
  Total number of objects deleted:          0
  Total number of objects expired:          0
  Total number of objects failed:           0
  Total number of bytes transferred:   767.71 KB
  Data transfer time:                    1.16 sec
  Network data transfer rate:          661.82 KB/sec
  Aggregate data transfer rate:        186.33 KB/sec
  Objects compressed by:                    0%
  Elapsed processing time:           00:00:04

To archive a directory tree add a terminating slash to the file path and include the -su=yes option to recurse through the subdirectories, as below.

  tsm> ar "C:\My Documents\html-docs\Mac\" -su=yes

6. Retrieving your data

6.1. Retrieving selected files

Unlike the TSM GUI, you cannot get a straight list of archived files which you can retrieve. As a result you will probably wish to query the server for a list of files, before retrieving a (sub)selection of them. Basic queries are listed in the examples above ( see section querying the server ). Having done that, the basic syntax for archive file retrieval is dsmc retrieve source-file destination-file. If the destination-file is omitted then TSM will retrieve the file(s) to their original location. If a file of the same name is found in the destination location, TSM will prompt you whether to overwrite or not the current file.

The simplest form of retrieve is for a single file or file pattern

  tsm> retr join.jpg

The file may be wildcarded to specify more than one file, as below.

  tsm> retr j*.*

6.2. Retrieving multiple files and directories

To retrieve all files in a directory add a trailing slash on the end of the file path:

  tsm> retr "C:\My Documents\html-docs\Mac\"

When specifying an alternative destination for retrieved files, remember to terminate it with a trailing slash:

  tsm> retr "C:\My Documents\html-docs\Mac\"  C:\retrieve       # Wrong !
Retrieve function invoked.

--- User Action is Required ---
File '\\cles.oucs:c$\retrieve' exists

  tsm> retr "C:\My Documents\html-docs\Mac\"  C:\retrieve\      # Correct !

To retrieve all files in a directory tree, add the trailing slash on the end of the file path and include the -su=yes

  tsm> retr "C:\My Documents\html-docs\Mac\"  C:\retrieve\  -su=yes

By default TSM will create a subdirectory in the destination directory for each lowest level source directory, and place files in there. Thus, in the example above, if there were two subdirectories new and old under \html-docs\Mac\, then TSM would create two subdirectories named new and old under C:\retrieve\. This behaviour can be modified by using the -preservepath= option - see the online help for worked examples of the four values this option can take.

6.3. Retrieving selected archive versions of files

Where more than one version of a file has been archived, then a basic retrieve using just the file path will cause TSM to retrieve each version of that file, starting with the earliest and ending with the most recent archive copy. Once the earliest copy has been retrieved, TSM will prompt to overwite it with each more recent archive copy. To prevent this happening the -description= option should be used in both the query of archived files and the subsequent retrieval of files.

Thus, to query the server for just a subset of files archived under a certain path, run something like:

  tsm> q ar /scratch/test1/j*.jpg  -desc="Jenkins*"
       Size  Archive Date - Time    File - Expires on - Description
       ----  -------------------    -------------------------------
  2,411,227  28-06-2002 10:51:37    /scratch/test1/j1.jpg Never Jenkins 1st Initial Scan
  2,411,227  30-06-2002 15:07:24    /scratch/test1/j1.jpg Never Jenkins 1st - 1st amend
  2,411,227  01-07-2002 12:01:06    /scratch/test1/j1.jpg Never Jenkins 1st - 2nd amend
  2,411,227  01-07-2002 12:01:06    /scratch/test1/j1.jpg Never Jenkins 1st Final Version
    760,632  28-06-2002 10:51:37    /scratch/test1/j2.jpg Never Jenkins 2nd Initial Scan
    760,632  28-06-2002 16:46:03    /scratch/test1/j2.jpg Never Jenkins 2nd - 1st amend
    760,632  28-06-2002 17:18:54    /scratch/test1/j2.jpg Never Jenkins 2nd - 2nd amend
    760,632  28-06-2002 17:22:28    /scratch/test1/j2.jpg Never Jenkins 2nd - 3rd amend
    760,632  01-07-2002 12:01:06    /scratch/test1/j2.jpg Never Jenkins 2nd Final Version

To retrieve just the Final Version of the above files to their original location on the local machine:

  tsm> retr /scratch/test1/j*.jpg  -desc="Final Version"

7. Retrieving your data to another machine

In certain circumstances, it may be necessary to retrieve some, or all, of your archive data onto a machine other than the original source machine. To do this you will need to have installed the same version TSM client software on the new machine and have the TSM password for the original machine to be restored from. The retrieval of data is only possible on similar filesystem types; thus a Unix - to - Unix retrieve will probably work, a Windows FAT - Windows NTFS retrieve will also work, but a Unix - to - Windows FAT or Mac HFS - to Windows will not work.

To access files from another machine start the TSM client as below:

  dsmc -virtualnodename=MYPC.OUCS  -se=OX_HFS	** Windows
  dsmc -virtualnodename=MYSOL.OUCS -se=OX_HFS	** Unix

Alternatively, you can alter the Nodename option in the configuration file to that of the original machine and access files as the other machine by starting the TSM archive client in the usual way.

  dsmc  -se=OX_HFS	** Windows
  dsmc  -se=OX_HFS	** Unix

If this is your preferred method of accessing the data, then you should ensure that the TSM sofwtare version on the new machine matches that of the original machine. In particular, you should not use a higher version-level of TSM client on the new machine if you intend to re-access the archive data from the original machine sometime in the future.

Querying and retrieving the archive filestore is then as in the previous section with the caveat for Unix users that: if you archived the files under a username on the source machine that does not exist on the new machine, you will have to retrieve the files as the root user.

8. Authorizing another user to retrieve your files

By default, TSM allows only the user who archived the files to retrieve them. The general exception to this is that the (Unix)root user and (Windows)system account can retrieve any files. You can authorise other users to retrieve archived files by using the following basic syntax: set access archive filespec node username. Thus to grant the generic login "operator" on the current machine access to retrieve archived files from the /project/01 filespace, you would issue the following:

  tsm> set acc archive /project/01/*/* current.node operator

The equivalent commands on Windows machines would look like:

  tsm> set acc archive c:\project\01\*\* current.node  operator

The current access list can be queried and deleted using the query acc and delete acc commands.

Once access has been granted from another machine, you can query and retrieve archived files from that machine to your local machine using the -fromnode option, as below:

  tsm> q ar -fromnode=ANOTHER.NODE
  tsm> ret -fromnode=ANOTHER.NODE /project/*/*  /home/retrieve/

9. Deleting archived files

Unlike with OUCS Backup policy, users are authorised to delete archived files. The caveat is that users should be cautious about this, as deleted files are lost forever. Neither OUCS nor the user can retrieve or "undelete" files once they have been deleted.

With the above in mind the basic syntax is:

  tsm> del ar /filename
  tsm> del ar /path/to/files/*.*

A safer option may be to choose which files to delete from a list. To do this, use the -pick option.

  tsm> del ar -pick /scratch/test1/*
  tsm> del ar -pick "C:\My Documents\html-docs\*"

In all cases the user is prompted for final confirmation when deleting archived files.

10. Changing your TSM password

The TSM password is set to expire approximately one year after registration and at one-yearly intervals after that. Prior to this automatic expiry, you will be contacted to remind you to re-set this password. Note that even if you have the option 

   PASSWORDACCESS  Generate

set in your options file, it is recommended you manually re-set your TSM password. To do this at the tsm> prompt enter:

 tsm>  set password  oldpassword  newpassword