I received this from another forum participant. I'm not sure if he wants
his role known, so I removed his personal content.
The syntax for Clean Archdirs command changed between ADSM 3.1 and TSM.
This is for TSM 4.1 and **maybe** for TSM 3.7.
Tivoli Tech Support took three days to tell me that there was "no
documentation" on this command.
Tab Trepagnier
TSM (4.1) Administrator
Laitram Corporation
----------- Begin technical document ----------------------
Archive Description and Directory Utilities
There have been a number of PMRs in the past year that involve archive
processing These include:
the API client does not support efficient query or retrieve by
description
unsatisfactory performance when archiving a file using a 3.1.0.7 client
and a 3.1.2.40 server
storage administrators who have used ADSM from Version 2 have noticed
large increases in database space requirements after upgrading to
Version 3 servers and clients
expiration performance is degraded when processing large numbers of
archive objects
These problems all have their roots in changes where the Version 3 client
began to archive directories, introduced the idea of archive packages using
the description field as the package handle, and the GUI changed to a tree
structured presentation for retrieve:
3.1.0 to 3.1.0.6 clients generated a default description that included a
timestamp with millisecond granularity. To prevent the archive
directories from expiring before a file that references them, they were
bound to the management class with the longest retention and
unconditionally archived each time the archive function was invoked.
(Note that when a client specified the same description to archive files
from the same directory sub-tree, duplicate directory entries were
archived.) The primary Archive.Objects and secondary
Arch.Objs.ByDescription tables grew unexpectedly especially when
hundreds of files were archived daily, one at a time, from tools that
invoked the command line client.
to reduce the number of directory entries, the 3.1.0.7 and higher
clients removed the timestamp from the default description, stored one
entry for each directory that is unique by hl,ll AND description (no
duplicates), bound archive directories to the management class with the
shortest retention and expired only directories that were not
referenced. When archiving a file, the client now queries the server to
determine if the directory/description structure exists: the
directories are inserted when they do not already exist. Customers who
archive files frequently noticed "hangs" and high CPU utilization when
archiving new entries while the server utilized MIPs to query in tables
flooded with directory entries. Expiration performance degraded because
each directory that is eligible to be expired is now tested to determine
if the entry is referenced.
Despite these changes, the quantity of entries can be exacerbated when a
client archives hundreds of files a day, one at a time, and uses a new
description for each archive request.
The server ptf 3.7.40 and ptfs for subsequent versions address these
problems:
a new CONVert ARCHive command allows administrators to convert a node to
the description tables. Conversion is no longer dependent on using a
GUI client. This command is documented by apar ic27865 and is a fix
for iy08295.
a new Arch.Description.Objects table has been introduced to improve
archive search performance for clients with large numbers of archive
entries. The existing Arch.Objs.ByDescription table continues to be
supported: customers are not required to change to the new table. All
new conversions use the new table, and an administrator can force
conversion to the new table using an undocumented option to the CONVert
ARCHive command.
a new DELETEDIrs option has been added to the CLEAN ARCHDIR utility to
allow administrators to delete all archive directories for a node.
Deleting the directories will reduce the space requirements for the
Archive.Objects and Arch.Objs.ByDescription or Arch.Description.Objects
tables and improve expiration performance.
the 4.1.2 client offers a new archive option, -v2Archive, which
suppresses archiving the directory structure
The latter 3 bullet items are fixes for iy08292.
The changes are documented in:
the Archive Revisited line item design document
ic27865
this document written for service personnel
Commands available to manage archive problems:
(Note: the syntax of the CLEAN ARCHDIR utility has been changed. The
new syntax and functions are available for TSM server version 3.7 and
higher, and for the 3.1.2.90 ADSM server.)
CLEAN ARCHDIR <nodeName> {DELETEDUplicates [Format=S|D] [Wait=No|Yes]
| SHOWstats
| RESETDescr
| 1DELETEDIrs }
where <nodeName> and 1 of 4 functions is required:
DELETEDUplicates - removes duplicate directories. This functions was
designed for directories archived by clients between 3.1.0 and
3.1.0.6.
SHOWstats - counts and displays the number of filespaces, directories
and files for a node. It also determines how many directories are
unique by hl and all, and the number of duplicates. This was added
because, for large archive tables, the server may run out of
temporary table space when obtaining this information via SQL
queries. Use this function to determine if the quantity of
directories might be causing performance problems when inserting,
querying, retrieving or deleting archive files, or the number of
entries that will be deleted by the RESETDescr and DELETEDIrs
functions. RESETDescr will delete the number reported by the
"duplicates" field. DELETEDIrs will delete the total number of
directories.
RESETDescriptions - sets the description field of archive table
directory and file entries to the null string. The resulting
"duplicate" directories are also deleted (we keep the most recent
entry). The function is performed on a node that is NOT converted.
An error is returned if the node is converted.
!!!!!!*****!!!!!*****!!!!! WARNING !!!!!*****!!!!!*****!!!!!!
! Use this function only when the description field is not !
! important to the user (e.g. for query and retrieve). !
! THE DESCRIPTIONS FOR ALL FILE AND DIRECTORIES FOR A NODE !
! WILL BE RESET TO "". !
!!!!!!*****!!!!!*****!!!!! WARNING !!!!!*****!!!!!*****!!!!!!
To use:
verify that the node does not need its descriptions
gather initial file and unique directory counts, where a directory
is unique by nodeName, filespaceName, objectType, hlName and
llName. The SHOWstats option may be used to collect these
statistics.
** BACKUP THE DATABASE **
if the node is converted, issue: DELete ARCHDescriptions
<nodeName>
issue: CLEAN ARCHDIR <nodeName> RESETDescriptions
gather file and unique directory counts again, and compare to step
2. The unique directory and file counts should match, providing
no inserts or deletes occurred for this node between steps 2 and
6. query and retrieve a few selected files
DELETEDirs - deletes all archive table directory entries for a node
regardless of conversion status. Since this function preserves the
description field for files, use it to reduce the number of archive
table entries when description is important to the customer.
!!!!!!*****!!!!!*****!!!!! WARNING !!!!!*****!!!!!*****!!!!!!
! Access and other attribute information stored by some !
! clients for directories will not be available when they !
! rebuild the directory path to a file during a retrieve !
!!!!!!*****!!!!!*****!!!!! WARNING !!!!!*****!!!!!*****!!!!!!
To use:
verify that the node does not need the ACL information stored for
the directories
gather initial file and unique directory counts, where a directory
is unique by nodeName, filespaceName, objectType, hlName and
llName. The SHOWstats option may be used to collect these
statistics.
** BACKUP THE DATABASE **
if the node is converted, issue: DELete ARCHDescriptions
<nodeName>
issue: CLEAN ARCHDIR <nodeName> DELETEDIrs
gather file and unique directory counts again, and compare to step
2. The file counts should match, and directory counts should be
zero. query and retrieve a few selected files
Format may be Standard or Detailed, and defaults to Standard
Wait may be No or Yes, and defaults to No. Yes is available only to
admin clients, and may not be issued from the system console.
DELete ARCHDescriptions <nodeName>
This command deletes a node from the archive description tables. It
runs in the background to prevent the server console from hanging,
and is started as a cancelable process, which allows administrators to
take snapshot progress reports.
CONVert ARCHive <nodeName> REORG=No|Yes
The REORG option is an undocumented option that allows an
administrator to reorganize a node that is already converted using the
old table, to the new description table with improved description
search characteristics. Processing will initially "unconvert" the
node, make entries in the new table, then remove entries from the old
table. Note that all new conversions initiated after the 3.7.40 ptf
has been applied, will use the new table.
Trace options
To diagnose archive problems, use:
ARCH - for archive query, delete and new archive inserts
ARCHD - for detailed traces of the above
ARCHUTIL - to trace the CLEAN ARCHDIR, DELete ARCHDescriptions and
CONVert ARCHive commands
To diagnose archive query, delete and inserts problems, also use:
SESSION
SYSTIME
When to use the above commands:
|------------------------+---------------------------------------------|
| Symptom | Suggestions: |
|------------------------+---------------------------------------------|
|a customer using a 3.1.0| determine the number of archive entries: |
|or higher ADSM or TSM | CLEAN ARCHDIR <nodeName> SHOWstats |
|server and a 3.1.0 or | |
|higher client | If there is a large number of directory |
|experiences poor | entries, reduce the number of entries by: |
|performance when | CLEAN ARCHDIR <nodeName> DELETDUplicates |
|archiving new files, | if the node uses a 3.1.0 to 3.1.0.6 |
|issuing archive queries | client |
|that include | |
|directories, when | or, CLEAN ARCHDIR <nodeName> RESETDescr |
|deleting archive | if the node does not use descriptions to |
|directories and files, | query or retrieve its archive files. |
|during expiration. | 3.1.0.7 and later clients should always |
| | specify a description of " " (a blank) to|
|(This problem is | suppress the default description for |
|especially experienced | further archives. |
|by clients that archive | |
|large numbers of files | or, CLEAN ARCHDIR <nodeName> DELETEDIrs |
|daily, each with a | if the node does not need the access and |
|unique description, one | other information stored with |
|at a time, using a tool | directories. Further archives using a |
|that invokes the command| 4.1.2 client or later should use the |
|line client.) | -v2Archive option to suppress archiving |
| | the directories. |
|------------------------+---------------------------------------------|
|a customer using a 3.1.0| reduce the number of directory entries, |
|or higher server and | as above, if possible |
|3.1.0 or higher GUI or | |
|command line client | if the client specifies unique |
|experiences "hangs" when| descriptions with each file, convert or |
|archiving new files. | reorganize the node: |
| | if the node is NOT converted, issue: |
| | CONVert ARCHive <nodeName> |
| | if the node IS converted, issue: |
| | CONVert ARCHive <nodeName> REORG=Yes |
|------------------------+---------------------------------------------|
|an API client |convert the node to the description tables |
|experiences delays when |using the CONVert ARCHive <nodeName> command |
|querying, archiving or | |
|retrieving files using | |
|the description option | |
|------------------------+---------------------------------------------|
|a node has been |remove the node from the description tables |
|converted and: |using the DELete ARCHDescriptions <nodeName> |
| the customer needs to|command. |
| use the | |
| DELETEDUplicates, | |
| RESETDescrs or | |
| DELETEDIrs options of| |
| the CLEAN ARCHDIR | |
| utility | |
| or, a node that | |
| archives using the | |
| command line or API | |
| no longer uses | |
| descriptions to query| |
| or retrieve files | |
| (GUI clients always | |
| use the description | |
| tables) | |
|------------------------+---------------------------------------------|
