QUERY CONTENT (Query the contents of a storage pool volume)

Use this command to display information about files in a storage pool volume, and the names of client files that link to a deduplicated group of files.

You can use this command to identify files that the server found to be damaged and files that were backed up to a copy storage pool or copied to an active-data pool. This command is useful when a volume is damaged or before you:

Request the server to fix inconsistencies between a volume and the database
Move files from one volume to another volume
Delete a volume from a storage pool

Because this command can take a long time to run and the results can be large, consider using the COUNT parameter to limit the number of files displayed.

Note: Files that are cached in a disk volume and that are marked as damaged are not included in the results.

Privilege class

Any administrator can issue this command.

Syntax


>>-Query CONtent--volume_name--+--------------------+----------->
                               '-NODE--=--node_name-'   

>--+-------------------------------+--+------------------+------>
   '-FIlespace--=--file_space_name-'  '-COUnt--=--number-'   

   .-Type--=--ANY--------------.  .-Format--=--Standard-----.   
>--+---------------------------+--+-------------------------+--->
   '-Type--=--+-ANY----------+-'  '-Format--=--+-Standard-+-'   
              +-Backup-------+                 '-Detailed-'     
              +-Archive------+                                  
              '-SPacemanaged-'                                  

                                     (1)             
   .-DAmaged--=--ANY-----.  .-COPied------=--ANY-.   
>--+---------------------+--+--------------------+-------------->
   '-DAmaged--=--+-ANY-+-'  '-COPied--=--+-ANY-+-'   
                 +-Yes-+                 +-Yes-+     
                 '-No--'                 '-No--'     

   .-NAMEType--=--SERVER------.   
>--+--------------------------+--------------------------------->
   '-NAMEType--=--+-SERVER--+-'   
                  +-UNIcode-+     
                  '-FSID----'     

   .-CODEType--=--BOTH-----------.   
>--+-----------------------------+------------------------------>
   '-CODEType--=--+-UNIcode----+-'   
                  +-NONUNIcode-+     
                  '-BOTH-------'     

   .-FOLLOWLinks--=--No------------.   
>--+-------------------------------+---------------------------><
   '-FOLLOWLinks--=--+-No--------+-'   
                     +-Yes-------+     
                     '-JUSTLinks-'

Notes:

Use this parameter only for volumes in primary storage pools.

Parameters

volume_name (Required)

Specifies the volume to be queried.

NODE

Specifies the backup-archive client or the Tivoli® Storage Manager for Space Management associated with the file space to query. This parameter is optional. You can use wildcard characters to specify this name. If you do not specify a name, all backup-archive and Tivoli Storage Manager for Space Management clients are included.

FIlespace

Specifies the file space to query. This parameter is optional. You can use wildcard characters to specify this name. File space names are case-sensitive. If you do not specify a file space name, all file spaces are included.

For a server that has clients with Unicode support, you might need to have the server convert the file space name that you enter. For example, you might need to have the server convert the name that you enter from the server's code page to Unicode. See the NAMETYPE parameter for details. If you do not specify a file space name or specify only a single wildcard character for the name, you can use the CODETYPE parameter to limit the operation to Unicode file spaces or non-Unicode file spaces.

COUnt

Specifies the number of files to be displayed. This parameter is optional. You can specify either a positive integer or a negative integer. If you specify a positive integer, n, the first n files are displayed. If you specify a negative integer, -n, the last n files are displayed in reverse order. You cannot specify COUNT=0. If you do not specify a value for this parameter, all files are displayed.

Type

Specifies the types of files to query. This parameter is optional. The default value is ANY. If the volume that is being queried is assigned to an active-data pool, the only valid values are ANY and BACKUP. Possible values are:

ANY: Specifies that all types of files in the storage pool volume are queried; backup versions of files, archived copies of files, and files that are migrated by Tivoli Storage Manager for Space Management clients from client nodes.
Backup: Specifies that only backup files are queried.
Archive: Specifies that only archive files are queried. This value is not valid for active-data pools.
SPacemanaged: Specifies that only space-managed files (files that were migrated by a Tivoli Storage Manager for Space Management client) are queried. This value is not valid for active-data pools.

Format

Specifies how the information is displayed. This parameter is optional. The default value is STANDARD. Possible values are:

Standard: Specifies that partial information is displayed. Unicode names are converted to the server code page.
Detailed: Specifies that complete information is displayed. Unicode names are displayed in hexadecimal.

DAmaged

Specifies criteria to restrict the query output based on whether files are marked as damaged. For purposes of this criteria, the server examines only physical files (a file that might be a single logical file or an aggregate that consists of logical files). This parameter is optional. The default value is ANY. Possible values are:

ANY: Specifies that files are displayed regardless of whether the server found the files to be damaged.
Yes: Specifies that only files that are marked as damaged are displayed. These are files in which the server found errors when a user attempted to restore, retrieve, or recall the file, or when an AUDIT VOLUME command was run.
No: Specifies that only files not known to be damaged are displayed.

COPied

Specifies criteria to restrict the query output based on whether files were backed up to a copy storage pool. Whether files are stored in an active-data pool does not affect the output. This parameter is optional. The default value is ANY. Possible values are:

ANY: Specifies that files are displayed regardless of whether the files are backed up to a copy storage pool. Primary and cached file copies are displayed.
Yes: Specifies that the files displayed are only those for which at least one usable backup copy exists in a copy storage pool. A file is not displayed if its copy in the copy storage pool is known to have errors. Cached file copies are not displayed because these files are never restored.
Use COPIED=YES to identify primary files that can be restored using the RESTORE VOLUME or RESTORE STGPOOL command.
No: Specifies that the files displayed are only those for which no usable backup copies exist in a copy storage pool. Cached file copies are not displayed because these files are never restored.
Use COPIED=NO to identify primary files that cannot be restored using the RESTORE VOLUME or RESTORE STGPOOL command.

NAMEType

Specify how you want the server to interpret the file space names that you enter. This parameter is useful when the server has clients with Unicode support. A backup-archive client with Unicode support is currently available only for Windows, Macintosh OS 9, Macintosh OS X, and NetWare. Use this parameter only when you specify a partly or fully qualified file space name.

The default value is SERVER. Possible values are:

SERVER: The server uses the server's code page to interpret the file space names.
UNIcode: The server converts the file space names from the server code page to the UTF-8 code page. The success of the conversion depends on the actual characters in the names and the server's code page. Conversion can fail if the string includes characters that are not available in the server code page, or if the server has a problem accessing system conversion routines.
FSID: The server interprets the file space names as their file space IDs (FSIDs).

CODEType

Specify how you want the server to interpret the file space names that you enter. Use this parameter only when you enter a single wildcard character for the file space name.

The default value is BOTH, which means that the file spaces are included regardless of code page type. Possible values are:

UNIcode: Include file spaces that are only in Unicode.
NONUNIcode: Include file spaces that are not only in Unicode.
BOTH: Include file spaces regardless of code page type.

FOLLOWLinks

Specifies whether to display only the files that are stored on the volume or only files that are linked to the volume. You can also display both stored files and linked files. The default is NO. Possible values are:

No: Display only the files that are stored in the volume. Do not display files that have links to the volume.
Yes: Display all files, including files that are stored on the volume and any files that have links to the volume.
JUSTLinks: Display only the files that have links to the volume. Do not display files that are stored on the volume.

Example: Display the contents of a volume for a specific client node

Query the contents of a volume and limit the results to files backed up from the PEGASUS client node.

For the volume /tsmstg/diskvol1.dsm, issue the command:

query content /tsmstg/diskvol1.dsm node=pegasus
 type=backup

For the volume f:\tsmstg\diskvol1.dsm, issue the command:

query content f:\tsmstg\diskvol1.dsm node=pegasus
 type=backup

Results of the command include all logical files that make up any aggregate that is on the volume, even if the aggregate is stored on more than this volume. For aggregates, the query does not determine which logical files are actually stored on the volume for which the query is performed.

Node Name        Type  Filespace   FSID  Client's Name for File
                       Name                                    
---------------  ----  ----------  ----  ----------------------
PEGASUS         Bkup  \\pegasus\e$   1   \UNI_TEST\ SM01.DAT   
PEGASUS         Bkup  \\pegasus\e$   1   \UNI_TEST\ SM02.DAT

See Field descriptions for field descriptions.

Example: Display detailed information for a tape volume

Query the contents of the tape volume named WPD001. Display only files that are backed up by the node MARK, and files that are either stored on the volume or linked to the volume. Display only the first four files on the volume.

query content wpd001 node=mark count=4 type=backup followlinks=yes
 format=detailed

                         Node Name: MARK
                              Type: Bkup
                    Filespace Name: \\mark\e$
        Hexadecimal Filespace Name: 
                              FSID: 1
            Client's Name for File: \UNI_TEST\ SM01.DAT
Hexadecimal Client's Name for File: 
                       Aggregated?: 1/3
                       Stored Size: 2,746
                    Segment Number: 
                      Cached Copy?: No
                           Linked?: No
                   Fragment Number:

                         Node Name: MARK
                              Type: Bkup
                    Filespace Name: \\mark\e$
        Hexadecimal Filespace Name: 
                              FSID: 1
            Client's Name for File: \UNI_TEST\ SM02.DAT
Hexadecimal Client's Name for File: 
                       Aggregated?: 2/3
                       Stored Size: 2,746
                    Segment Number: 
                      Cached Copy?: No
                           Linked?: No
                   Fragment Number: 2

                         Node Name: MARK
                              Type: Bkup
                    Filespace Name: \\mark\e$
        Hexadecimal Filespace Name: 
                              FSID: 1
            Client's Name for File: \UNI_TEST\ SM03.DAT
Hexadecimal Client's Name for File: 
                       Aggregated?: 3/3
                       Stored Size: 2,746
                    Segment Number: 
                      Cached Copy?: No
                           Linked?: No
                   Fragment Number: 3

See Field descriptions for field descriptions.

Field descriptions

Node Name

The node to which the file belongs.

Type

The type of file: archive (Arch), backup (Bkup), or space-managed (SpMg) by a Tivoli Storage Manager for Space Management client.

Filespace Name

The file space to which the file belongs.

File space names can be in a different code page or locale than the server. If they are, the names in the Operations Center and the administrative command-line interface might not be displayed correctly. Data is backed up and can be restored normally, but the file space name or file name might be displayed with a combination of invalid characters or blank spaces.

If the file space name is Unicode-enabled, Tivoli Storage Manager converts the name to the server code page for display. The success of the conversion depends on the operating system, the characters in the name, and the server code page. Conversion can be incomplete if the string includes characters that are not available in the server code page or if the server cannot access system conversion routines. If the conversion is incomplete, the name might contain question marks, blanks, unprintable characters, or ellipses (...).

Hexadecimal Filespace Name

The file space to which the file belongs. If the file space name is in Unicode, the name is displayed in hexadecimal format.

FSID

The file space ID (FSID) for the file space. The server assigns a unique FSID when a file space is first stored on the server.

Client's Name for File

The client's name for the file.

File space names and file names that can be in a different code page or locale than the server do not display correctly in the Operations Center or the administrative command-line interface. The data itself is backed up and can be restored properly, but the file space or file name might display with a combination of invalid characters or blank spaces. The results of the conversion for characters that are not supported by the current code page depends on the operating system. For names that Tivoli Storage Manager is able to partially convert, you might see question marks (??), blanks, unprintable characters, or "...". These characters indicate to the administrator that files do exist.

Hexadecimal Client's Name for File

The client's name for the file that is displayed in hexadecimal format.

Aggregated?

Whether the file is a logical file that is stored as part of an aggregate. If the file is part of an aggregate, the sequence of this file within the aggregate and the total number of logical files in the aggregate are displayed. Results of the command include all logical files that make up any aggregate that is on the volume, even if the aggregate is stored on more than this volume. The query does not determine which logical files are actually stored on the volume for which the query is performed.

If the file is not part of an aggregate, the field displays "no".

Stored Size

The size of the physical file, in bytes. If the file is a logical file that is stored as part of an aggregate, this value indicates the size of the entire aggregate.

Segment Number

For volumes in sequential-access storage pools, specifies whether the physical file (either a single logical file or an aggregate of logical files) is stored across multiple volumes. For example, if the logical file is stored in an aggregate that spans two volumes, the segment number indicates 1/2 (the first part of the physical file is stored on the volume) or 2/2 (the second part of the physical file is stored on the volume). If the segment number is 1/1, the physical file is completely stored on the volume. For volumes in random-access storage pools, no value is displayed for this field.

Cached Copy?

Whether the physical file is a cached copy of a file migrated to the next storage pool. If the file is part of an aggregate, this value pertains to the aggregate.

Linked?

Indicates whether the file is stored on the volume or whether the file is linked to the volume.

Fragment Number

Specifies the fragment number. If the fragment number is blank, it is either the first fragment or not a fragment.

Related commands

Table 1. Commands related to QUERY CONTENT
Command	Description
BACKUP STGPOOL	Backs up a primary storage pool to a copy storage pool.
COPY ACTIVEDATA	Copies active backup data.
DEFINE VOLUME	Assigns a volume to be used for storage within a specified storage pool.
DELETE VOLUME	Deletes a volume from a storage pool.
RESTORE STGPOOL	Restores files to a primary storage pool from copy storage pools.
RESTORE VOLUME	Restores files stored on specified volumes in a primary storage pool from copy storage pools.
UPDATE VOLUME	Updates the attributes of storage pool volumes.