Skip Headers
Oracle Hierarchical Storage Manager and QFS Software Command Reference
Section 1m: Maintenance Commands
Release 6.1.1


sam-recycler - Recycles Oracle HSM volumes


∕opt∕SUNWsamfs∕sbin∕sam-recycler [-b] [-c] [-C] [-d] [-E] [-n] [-s] [-t] [-v] [-V] [-x] [-X] [family_set | archive_set]




The sam-recycler command invokes the recycler. The recycler removes expired archive copies and frees up archive volumes. Often, the recycler is invoked through root's crontab (1) file at an off-peak time. However, the recycler can be invoked at any time.

You can specify that only a specific library or archive set be recycled. You can recycle by library only when archiving to tape or magneto optical cartridges in a library. Note that you cannot recycle by library if you are using disk archiving.

If you want to recycle by archive set, you must name the archive sets to be recycled in the ∕etc∕opt∕SUNWsamfs∕archiver.cmd file.

You can provide directives to the recycler through lines entered in the ∕etc∕opt∕SUNWsamfs∕recycler.cmd file and in the ∕etc∕opt∕SUNWsamfs∕archiver.cmd file. If no directives are present and no family_set or archive_set is specified on the command line, recycling does not occur. The following are the default recycler settings:

NOTE: Extreme care must be taken when configuring the recycler if you are using disk archiving in an environment with multiple Oracle HSM servers. The diskvols.conf file for each Oracle HSM server must point to a unique set of disk volume resource specifications (disk archiving target directories). If any of these are shared between different Oracle HSM servers, then running the recycler from one Oracle HSM server will destroy the disk archive data that is being managed by the other Oracle HSM server.


The following options determine the volumes to be recycled and the content of the recycler log file.


Displays the capacity and remaining space for each volume in base 10 units in the recycler log file. By default, space is displayed in base 2 units.


Displays the extrapolated capacity of each volume. This is the volume's capacity assuming the compression observed on the volume so far continues for the rest of the volume. This option produces an additional line for each volume with the heading Alpha:.


Suppresses listing of initial catalog(s).


Displays messages during the volume selection phase of processing. These messages indicate why each volume was, or was not, selected for recycling.


Specifies that the volume section of the recycler's log file list only volumes that are not 100% free.


Prevents any actions from being taken. This option causes ∕opt∕SUNWsamfs∕sbin∕sam-recycler to behave as if -recycle_ignore were specified in the ∕etc∕opt∕SUNWsamfs∕archiver.cmd file for all archive sets.


Suppresses the listing of individual volumes in the initial catalog section.


Recycle tape volumes only.


Displays information about which files are resident on the volume that is marked for recycling. If no path name can be calculated for the inode, it lists the inode. These files are on volumes that are being drained. Using this option can consume a lot of CPU cycles.


Suppresses the volume section in the listing.


Displays messages for expired archive copies. These are copies that are older than the time the volume upon which the copies reside was labeled. Such copies generate an error message when staged. The data for those copies is irrecoverable. These archive copies must be unarchived. If any such copies are discovered, the recycler stops. This is the default behavior. Also see the -X option.


Inhibits the messages that indicate the existance of expired archive copies. Typically, if the recycler detects expired archive copies, it stops. Use this options if you want the recycler to continue in the presence of expired archive copies. Also see the -x option.

family_set | archive_set

Recycles only the named family_set or archive_set. This is an optional argument. If a family_set is specified, the library associated with the family set is recycled. The family set is the fourth field in a server's mcf file. If an archive_set is specified, that archive set is recycled. The archive_set specified must include the copy number, as stated in the ∕etc∕opt∕SUNWsamfs∕archiver.cmd file. For example, arset.1.

If no family_set or archive_set name is specified, the recycler recycles according to specifications in the ∕etc∕opt∕SUNWsamfs∕archiver.cmd and the ∕etc∕opt∕SUNWsamfs∕recycler.cmd files. It examines each library and archive set specified.

Regardless of a specification, only archive sets and family sets that have a current usage that is less than the high-water mark are recycled.


The recycler splits its work into two phases: volume selection and volume recycling.

Phase 1 - Volume Selection

The recycler selects volumes for recycling based on the amount of space used by expired archive copies as a percentage of total space on a volume. For each library or archive set being recycled, the volumes with the highest percentages of expired copies are selected to bring the media utilization in the library or archive set below the configured high-water-mark. This assumes that each volume selected would contribute at least VSN-minimum-percent-gain percent of its total space if it were recycled. If no such volumes exist, the library or archive set cannot be recycled. Ties in expired space are resolved by selecting the volumes with the least amount of unexpired space. For more information on setting a high water mark, see the recycler.cmd (4) man page.

A few conditions can prevent a volume from being selected. A volume cannot be recycled if it contains data associated with a removable media file created by the request (1) command. In addition, it cannot be recycled if it is listed in the ∕etc∕opt∕SUNWsamfs∕recycler.cmd file's no_recycle section.

After volumes have been selected, they are recycled.

Phase 2 - Volume Recycling

Volume recycling differs depending upon whether the archive media is a disk volume or whether it is a removable cartridge in a library. Archiving to disk volumes is described first.

When a disk volume is selected for recycling, the volume is not marked for recycling. Additional archive copies can be written to it. Expired archive copies on the disk volume are identified and removed. Valid archive copies are left alone.

When a tape or magneto optical volume is selected for recycling, the system prevents additional archive copies from being written to it. If you are recycling to cartridges in a library, all files with active archive copies in volumes on the cartridges are marked to be re-archived. The archiver moves these copies to other volumes. In subsequent runs, the recycler checks these volumes and post-processes them when all valid archive copies have been relocated.

The recycler checks to see if there are volumes that were selected for recycling that have not yet been post-processed. If such volumes exist, and they are now devoid of active archive copies, the sam-recycler command invokes the ∕etc∕opt∕SUNWsamfs∕scripts∕ (1m), which post-processes these volumes with arguments including the generic media type (tp or od), the VSN, the element address in the library, and the equipment number of the library in which the volume resides. The script can relabel the cartridge using either the original VSN or a new VSN; or it can export the cartridge from the library; or it can perform another user-defined action.

The ∕etc∕opt∕SUNWsamfs∕scripts∕ (1m) script clears the recycling flag to indicate that recycling has completed on the volume. The odlabel (1m) and tplabel (1m) commands clear this flag after the cartridge has been relabeled.


The recycler log is divided into several sections.

The first section describes each library catalog and archive set. The header contains the family set name or archive set name and the vendor, product, and catalog path name. Then, the capacity and remaining space for each volume appears, in bytes, with suffixes k, M, G, and T representing kilobytes, megabytes, gigabytes, and terabytes, respectively. In this log file, a kilobyte=1024 bytes, a megabyte=1024*1024 bytes, and so on by default. If -b option is specified, the capacity and remaining space for each volume appears, in base 10 units. Then, a summary, containing the total capacity and total space remaining is shown in bytes and as a percentage of space used. The recycling parameters set in the recycler and archiver command files are also shown.

The second section is a series of tables, one for each library and archive set that has associated volumes. The name of the library or archive set is shown just to the right of the ----Percent---- label. A tape volume can be associated with only one physical library. But same as disk volumes it can belong to multiple archive sets. Attempts to assign a volume to multiple archive sets are marked with a in multiple sets label. The following fields are displayed:

Field Name



A phrase giving the volume's recycle status, as follows:

empty VSN

The volume is empty of both expired and current archive images

full VSN

The volume has no free space, but it does have current archive images.

in multiple sets

The volume matches multiple archive sets in the ∕etc∕opt∕SUNWsamfs∕archiver.cmd file.

new candidate

The volume was chosen for recycling during this recycler run.

no-data VSN

The volume contains only expired archive images and free space.

no_recycle VSN

The volume is listed in the no_recycle section of the ∕etc∕opt∕SUNWsamfs∕recycler.cmd file.

archive -n files

The volume contains archive images for files now marked as archive -n.

old candidate

The volume was already marked for recycling before this recycler run.

request files

The volume contains archive images for removeable media files.

partially full

The volume contains both current archive images and free space.

shelved VSN

The volume is not currently located in any library.

Archives Count

The number of archive copies that are contained on this volume.

Archives Bytes

The number of bytes of archive copies contained on this volume.

Percent Use

The percentage of space in use on this volume by current archive copies. It is estimated by summing up the sizes of the archive copies on the medium. Because of compression, this value can overstate the amount of space actually used by these images. This is the amount of data that would need to be moved if the volume were selected for recycling.

Percent Obsolete

The percentage of space used on this volume for which no archive copies were found. This is the space that can be reclaimed by recycling this cartridge.

The Percent Obsolete value is calculated as follows:

100% - In Use - Free

Because In Use can overstate the actual space used (because of compression), the sum of In use + Free can exceed 100%, which renders Percent Obsolete to be a negative value. Although aesthetically unpleasing, this does not cause any problems in the operation of the recycler.

Percent Free

The percentage of free space remaining on this volume. This value comes directly from the library catalog. It gives the percent of the volume's total capacity that is available to hold new archive images.

For media that supports data compression, a best-guess value of the average compression is calculated from the ratio of the number of physical tape blocks consumed on the volume (that is, the difference of capacity - space) to the logical number of tape blocks written to the volume. The latter value is kept in the catalog. This ratio is then used to adjust the In Use value before it is written to the log file.

The first volume to appear in the log file, for each library or archive set, is the one most in need of recycling.

Here is an example recycler log file:

========== Recycler begins at Thu Feb  5 13:40:20 1998 ===========
3 catalogs:
0  Family: hy                   Path: ∕tmp∕y
   Vendor: Oracle HSM           Product: Historian           
   EA                    ty    capacity         space vsn
      (no VSNs in this media changer)
   Total Capacity:  0    bytes, Total Space Available: 0    bytes
   Media utilization 0%, high 0% VSN_min 0%
1  Family: ad40                 Path: ∕var∕opt∕SUNWsamfs∕catalog∕ad40
   Vendor: ADIC                 Product: Scalar DLT 448      
   EA                    ty    capacity         space vsn
      0                  lt        19.2G         0    DLT3                
      1                  lt        17.7G        17.6G DLT4N               
      5                  lt        17.7G        17.6G DLT6                
   Total Capacity:  54.6G bytes, Total Space Available: 35.2G bytes
   Media utilization 35%, high 75% VSN_min 50%
2  Family: arset0.1             Path: ∕etc∕opt∕SUNWsamfs∕archiver.cmd
   Vendor: Oracle HSM           Product: Archive set         
   EA                    ty    capacity         space vsn
      0                  lt         0            0    DLT5                
      1                  lt        19.2G         0    DLT3                
      2                  lt         0            0    DLT2                
      3                  lt        17.7G        17.6G DLT4N               
      4                  lt        17.7G        17.6G DLT6                
   Total Capacity:  54.6G bytes, Total Space Available: 35.2G bytes
   Media utilization 35%, high 80% VSN_min 50%
   Send mail to root when this archive set needs recycling.
6 VSNs:
---Archives---   -----Percent-----   
-----Status-----    Count    Bytes   Use Obsolete Free   Library:Type:VSN
shelved VSN          677    648.9M                       none:lt:DLT0
---Archives---   -----Percent-----   arset0.1
-----Status-----    Count    Bytes   Use Obsolete Free   Library:Type:VSN
no-data VSN            0      0        0   100      0    ad40:lt:DLT3
empty VSN              0      0        0     0      0  (NULL):lt:DLT2
empty VSN              0      0        0     0    100    ad40:lt:DLT6
full VSN               4     32.1k     0     0      0  (NULL):lt:DLT5
partially full         4     40.8k     0     0    100    ad40:lt:DLT4N
Recycler finished.

========== Recycler ends at Thu Feb  5 13:40:41 1998 ===========

Here is the corresponding archiver.cmd file:

interval = 2m
no_archive .
fs = samfs1
arset0 testdir0
     1 1s
     2 1s
     3 1s
     4 1s
no_archive .
fs = samfs2
no_archive .
arset0.1 lt DLT3 DLT4N DLT6 DLT1
arset0.2 lt DLT3 DLT4N DLT6 DLT1
arset0.3 lt DLT3 DLT4N DLT6 DLT1
arset0.4 lt DLT3 DLT4N DLT6 DLT1
samfs1.1 lt DLT3
samfs2.1 lt DLT4N
arset0.1 -drives 4 -recycle_hwm 80 -recycle_mingain 50

Here is the corresponding ∕etc∕opt∕SUNWsamfs∕recycler.cmd file:

logfile = ∕var∕tmp∕recycler.log
ad40 75 50  
no_recycle mo ^OPT003 


The recycler recycles volumes listed in the historian's catalog. The volumes listed in the historian catalog have been exported from a library or have been or are currently in a manually-mounted device.

The ∕etc∕opt∕SUNWsamfs∕scripts∕ (1m) script is passed the name hy, signifying volumes that reside in the historian catalog so that it can cope with the possibility of the volumes being recycled residing in an off-site storage facility. Typically, the ∕etc∕opt∕SUNWsamfs∕scripts∕ (1m) script sends email to the administrator when this occurs to remind the administrator to bring the off-site volume back on site so that it can be reused. Volumes do not need to be on site to be drained of archive copies unless such a volume contains the only available archive copy of an off-line file.


When the recycler recycles by archive set, it treats each archive set as a small library that holds just the volumes assigned to the archive set in the ∕etc∕opt∕SUNWsamfs∕archiver.cmd file. The volumes that are identified as belonging to a recycling archive set are removed from the recycler's version of the catalog for the library that physically contains the volume. Thus, only the volumes that are not part of an archive set remain in the library catalog.

To enable recycling for a given archive set, it must have one of the recycling options specified in the ∕etc∕opt∕SUNWsamfs∕archiver.cmd file. For more information, see the archiver.cmd (4) man page.


Consider the following message:

Jan 22 10:17:17 jupiter sam-recycler[3400]: Cannot ioctl(F_IDSCF)
      Cannot find pathname for filesystem ∕samfs1 inum∕gen 406∕25

The preceding message means that the recycler could not set the rearchive flag for a file. When this happens, the recycler typically emits a message containing the path name, as follows:

Jan 22 10:17:17 jupiter sam-recycler[3400]: Cannot ioctl(F_IDSCF)

However, in the first message, you see text beginning with Cannot find pathname…. This means that the recycler failed in its attempt to convert the inode number (in the preceding example message, it is inode number 406) and generation number (here, 25) into a path name in the ∕samfs1 file system.

The most likely reason for this to occur is that the file was deleted between the time that the recycler determined it needed to be rearchived and the time the recycler actually issued the system call to set the rearchive flag.