File Level Analytics - Command Line - XML

This approach to running File-Level Analytics commands is the preferred method for obtaining this information. It gives you greater flexibility and returns more information than the older, CSV-based approach.

Table of Contents

Overview of Querying Indexes for Data

You can browse backed-up file metadata by running queries against the index. Querying indexes provides a way to get information about files without having to touch the actual files. This gives flexibility in analyzing your backed-up data, and efficiency in obtaining the information you need. The XML Query Examples section of this page describes index query templates we provide, and the optional parameters they support.

The XML templates presented here provide examples of what can be done using XML-based queries. They are meant as starting points for your own queries. Each example builds on the ones before it, so we recommend reading through them in order if you are new to the subject.

Two basic kinds of query return names of one or more files. These are Browse and Find, which correspond to those same operations you can perform through the CommCell Console. The other operation described here, Versions, returns a list of available versions of a file that you name.

Supported Platforms

The XML-based queries described here use the qlist backupfiles command, and are supported for all agents.

General Procedure

The qlist backupfiles command takes input from an XML file you download and customize, and returns the results to another XML file that you name.

The basic procedure for performing index queries using this approach has these steps:

  1. From the XML Query Examples Provided table, locate the query you wish to perform. Download the XML template file for that query (linked in the example description), onto the client computer from which you will run the query command.
  2. Edit the template file, inserting these required parameters into their provided placeholders:
    Parameter Description
    entity clientName="clientName" The name of the client the backup set belongs to.
    entity subclientName="subclientName" The name of a subclient on the backed-up client computer.
    entity backupsetName="backupsetName" Name of the backup set to browse. If no name is specified, defaultBackupSet is used.
    paths path="path" For Browse operations, supply the path to a single folder containing the backed-up files. For example:

    E:\superbrowse\SC2 displays all data in the SC2 folder.

    For Find operations, which are recursive, wildcards are supported. For example:

    c:\User\Admin\Documents\**\* finds all files meeting filter criteria, starting at the Documents directory, including those in its subdirectories, the subdirectories of those, and so on. To find all files beginning at the root directory, use just "\**\*". Note that the syntax at the end of the path (\**\*) specifies performing a recursive search beginning at that point.

    For Versions operations, which return a list of the versions of a file available for restore, the last component of the path is a single filename. For example:

    F:\data1\data\test2\testa\testaa\cvfwd.log

  3. Modify the parameters listed in the Supported Elements and Parameters Used in Index Queries table if you find them in your query template and want to change the template's behavior accordingly. Values appearing in the template but not mentioned in the table should be left as supplied.
  4. Save your edited XML file.
  5. Log on to the CommServe computer.
  6. Change to the base installation directory:

    cd software_installation_path/Base

  7. Run the qlist backupfiles command, pointing to the XML file you edited:
  8. qlist backupfiles -af path_to_input_xml -dpath path_to_output_xml

  9. The command returns its output to the file you specify in the -dpath option, which you can redirect as needed using the operating system's built-in functionality.
  10. Log off of the CommServe Computer.

XML Query Examples Provided

This page provides these examples of XML queries:

Name Description
Browse Files in One Directory This query generates a listing of the all files and folders contained in one folder. The most basic query, presenting the minimum required elements.
Browse for Files Larger than a Size You Specify Generates a listing of the files in a folder that meet size criteria. Adds the whereClause element to the basic Browse query.
Find Files Finds all files in a tree, including those contained in folders, subfolders, etc., starting at the point in the directory tree that you specify. Uses the Find opType.
Find Files in Multiple Paths Find all files in more than one path.
Find Files in a Size Range Find all files in a tree, having a size between to values you specify.
Find Folders in a Size Range Find all folders in a tree, having a size between two values you specify.
Find Files by Modification Date Find files in a tree, filtering on a metadata field, in this case, file modification date.
Find Files by Backup Date Find files in a tree, filtering on the date the files or folders were backed up.
Browse for a File Name Returns a list of files with a name matching a pattern you specify.
Find Files Using Multiple Fields Find files in a tree, filtering on more than one metadata field, in this example, modification date and size.
Find Files Modified Yesterday Find files in a tree, filtering on a relative date.
Get a Count of Archived Files Returns the number of files that have been archived.
Browse for the Largest Files in
One Folder
Generates a list of files having the largest file size, where you can control the number of files listed.
List the Available Versions of a File Returns a list of the versions of a file that can be restored, if the file has been backed up more than once.

Log On to the CommServe Computer

To run command line operations, you must first login to the CommServe.

From Command prompt, navigate to <Software_Installation_Directory>/Base and run the following command:

qlogin -cs <commserve name> -u <user name>

For example, to log on to CommServe 'server1' with username 'user1':

qlogin -cs server1 -u user1

Log Off of the CommServe Computer

Once you have completed the command line operations, you can logout from the CommServe using the following command:

qlogout -cs commserve

For example, to log out from the CommServe 'Server1'.

qlogout -cs Server1

XML Query Examples

Browse Files in One Directory

This browse query is the simplest one, providing a basic building block upon which to build more complex queries. It presents the minimum required XML to run a query. As with Browse operations on the CommCell Console, this query returns the contents of one directory. Unlike the Find operation, Browse is not recursive. It does not traverse any folders that may be contained in the path folder that you specify; it only returns metadata for the files and folders contained in it.

To run this query, follow the steps described in General Procedure, using the browse_files_template.xml file.

Important

  • Folders are also returned with the file results, with a dataResultSet size attribute of size="0".
  • Archived files return the size of the actual file, not the stub.

Example

This example of the XML for this query shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Browse">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\test_docs"/>
    <queries type="DATA"/>
    <mode mode="2"/>
</databrowse_BrowseRequest>

You can modify the results this query returns by adding more elements to the XML. These elements are described in the sections that follow, as they are introduced. A list of all the available elements is provided in Supported Elements and Parameters Used in Index Queries. The XML structure that supports those optional elements is described in the sections that follow.

Browse for Files Larger than a Size You Specify

This XML template returns the names of all the files in one folder that meet size criteria you enter into the XML by adding a whereClause parameter to the queries element.

To run this query, follow the steps described in General Procedure using the browse_files_by_size_template.xml file.

Example

This example of the XML for this query shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Browse">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\test_docs"/>
    <queries type="DATA">
        <whereClause connector="AND">
            <criteria field="FileSize" dataOperator="GT" dataUnits="KB">
                <values val="20"/>
            </criteria>
        </whereClause>
    </queries>
    <mode mode="2"/>
</databrowse_BrowseRequest>

The whereClause element and its sub-elements (criteria and values) let you specify values to filter on and what tests to apply. In the example given above, some elements have been added to the basic Browse Files example given above. These include:

  • <whereClause>, which opens a place in the structure where you can enter testing criteria.
  • <criteria>, where you specify the file metadata field to test, the kind of test, and the units to apply to the value.
  • <values>, for specifying the value to test the field against, using the operator and units in the <criteria> element.

See Supported Elements and Parameters Used in Index Queries for more information on these elements and the supported values for them.

Important:

  • Folders are also returned with the file results, even though their dataResultSet size attribute is size="0".
  • Archived files filter on the size of the actual file, not the stub size.

Find Files

This basic XML template returns an unfiltered list of files, starting at the path folder. This query uses the Find value for opType, which can work recursively (starts at the path folder that you specify, descending into all subdirectories until the entire tree from your starting point downward has been traversed). The output supplies the complete path to each file or folder returned.

To run this query, follow the steps described in General Procedure, using the find_files_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="\**\*"/>
    <queries type="DATA">
    </queries>
</databrowse_BrowseRequest>

The primary difference between this example and the first example (Browse Files in One Directory) is the use of the Find value for opType (which supports recursive searching) and the path value (which supports wildcards when used with the Find opType). The double wildcard shown shown in the example requests recursive searching. See required parameters for details on the path value in Find operations.

Like all of these examples, you can take this template and add more XML to it or change its values to alter its behavior. See Supported Elements and Parameters Used in Index Queries for more information.

Find Files in Multiple Paths

To search multiple, independent paths in a single query operation, specify more than one <paths> element in a Find operation. The standard rules for wild card usage for Find operations apply to this query, which returns an unfiltered list of files, starting at each path folder, and recurring if you have used a double wildcard (see the second paths element in the example).

To run this query, follow the steps described in General Procedure, using the find_files_multi_path_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="\Users\Administrator\Documents\*"/>
    <paths path="\Users\jsmith\Documents\**\*"/>
    <queries type="DATA">
    </queries>
</databrowse_BrowseRequest>

This example returns information for files and folders contained in the Documents folders for the two users named in the paths (Administrator and jsmith). Note that this Find operation is not recursive for the Administrator account, but is recursive for the jsmith account, because of the recursive wildcard pattern, "\**\*" used for the jsmith path. You can put as many <paths> elements as you need.

Find Files in a Size Range

This query traverses the directory tree, starting at the path folder, and returns a list of files larger than a minimum size, but smaller than a maximum size.

To run this query, follow the steps described in General Procedure, using the find_files_in_size_range_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\test_docs\**\*"/>
    <queries type="DATA">
        <whereClause>
            <criteria field="FileSize" dataOperator="GT" dataUnits="KB">
                <values val="10"/>
            </criteria>
        </whereClause>
        <whereClause connector="AND">
            <criteria field="FileSize" dataOperator="LT" dataUnits="KB">
                <values val="50"/>
            </criteria>
        </whereClause>
    </queries>
</databrowse_BrowseRequest>

This example builds on the above Find Files example by adding of two whereClause structures to perform the filtering on file size. The additional parameter on the second whereClause element, connector="AND", defines the relationship between the two where clauses, AND requiring that both conditions must be met. The value for dataUnits can be any of the values supported for this parameter, listed in Supported Elements and Parameters Used in Index Queries.

Important:

  • Unlike Browse operations, Find operations do not return paths that end at folders, but do return their contents.
  • Archived files filter on the size of the actual file, not the stub size.

Find Folders in a Size Range

This XML template returns a list of all files in folders that fall between two folder sizes (in this example, larger than 10 megabytes, but smaller than 35 megabytes). Because this query uses the Find value for opType, it works recursively. It returns metadata for all folders found.

To run this query, follow the steps described in General Procedure, using the find_folders_in_size_range_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="indexingstorage_4" subclientName="sc1" backupsetName="scale_bkp" appName="File System" _type_="0"/>
    <paths path="F:\data1\data"/>
    <queries queryId="0" type="DATA">
        <whereClause>
            <criteria field="FolderSize" dataOperator="GT" dataUnits="MB">
                <values val="10"/>
            </criteria>
        </whereClause>
        <whereClause connector="AND">
            <criteria field="FolderSize" dataOperator="LT" dataUnits="MB">
                <values val="35"/>
            </criteria>
        </whereClause>
    </queries>
</databrowse_BrowseRequest>

The primary difference between this example and the one for finding files in a size range is the use of "FolderSize" for the criteria value.

Important: Although the where clauses do filter on folder size, the size indicated in the returned results (dataResultSet size) is 0 (zero).

You can modify the behavior of this query by changing some of its values in the XML, such as changing the value to dataUnits="KB" to test for file size in kilobytes rather than megabytes. See Supported Parameters Used in these Queries.

Find Files by Modification Date

This query traverses the directory tree, starting at the path folder, and returns a list of files that were modified on or after a certain date.

To run this query, follow the steps described in General Procedure, using the find_files_modified_after_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\test_docs\**\*"/>
    <queries type="DATA">
        <whereClause>
            <criteria field="ModifiedDate" dataOperator="GT">
                <values val="1399420800"/>
            </criteria>
        </whereClause>
    </queries>
</databrowse_BrowseRequest>

This example uses the whereClause structure to filter on a file modification date. The value you enter for ModifiedDate is the number of seconds since January 1, 1970 (that is, standard Unix timestamp format). Calculators are available on the Internet to convert between calendar time and Unix timestamp values. The output of this command also provides its date information in Unix format. Changing the GT to LT finds files modified before the timestamp date you enter, instead of after.

Find Files by Backup Date

You can filter on the date, or range of dates, that files and folders were backed up. As with the other queries that use opType=Find, this one works recursively if you specify recursion in the path element by using the double-asterisk notation, "**\*".

To run this query, follow the steps described in General Procedure, using the find_files_by_backup_date_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="doc_client2" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\xml_testing\*"/>
    <queries type="DATA">
    </queries>
    <timeRange>
        <fromTime>2014-08-27 00:00:00</fromTime>
        <toTime>2014-08-27 23:59:59</toTime>
    </timeRange>
</databrowse_BrowseRequest>

This example uses the timeRange structure to filter on the date when files or folders were backed up. A fromTime or a toTime parameter (or both) can be used. If using only one of these parameters, include the other parameter, but set it to 0. For example, to see files and folders backed up any time starting at August 27, 2014, use <fromTime>2014-08-27 00:00:00</fromTime> <toTime>0</toTime>.

View Properties of a File

This XML template returns the metadata for a file in one folder that matches the file name you enter in the path. Because it uses the opType of Browse, this query only searches the path folder.

To run this query, follow the steps described in General Procedure, using the browse_files_like_name_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Browse">
    <entity commCellId="2" clientName="indexingstorage_4" subclientName="sc1" backupsetName="scale_bkp" appName="File System" _type_="0"/>
    <paths path="F:\data1\data\test2\testa\testaa"/>
    <queries queryId="0" type="DATA">
        <whereClause connector="AND">
            <criteria field="FileName" dataOperator="LIKE">
                <values val="cvfwd.log"/>
            </criteria>
        </whereClause>
    </queries>
    <mode mode="2"/>
</databrowse_BrowseRequest>


This example makes use of the SQL "LIKE" operator for pattern matching. In this case, it is being applied to the fileName metadata field. Place the name of the file you are browsing for in the criteria...values...val field, where you see cvfwd.log in the example above.

Important: The LIKE function does not support using wildcards in these SnapProtect XML queries.

You can modify the some of the behaviors of this query by changing some of its values in the XML. See Supported Parameters Used in these Queries.

Find Files Using Multiple Fields

As you would expect, you are not limited to using only a single field when filtering. This query traverses the directory tree, starting at the path folder, and returns a list of files that meet criteria for two different fields (modified after a certain date and larger than a specific size). This is sometimes called a "hybrid" query.

To run this query, follow the steps described in General Procedure, using the find_files_using_multiple_fields_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\test_docs\**\*"/>
    <queries type="DATA">
        <whereClause>
            <criteria field="ModifiedDate" dataOperator="GT">
                <values val="1399420800"/>
            </criteria>
        </whereClause>
        <whereClause connector="AND">
            <criteria field="FileSize" dataOperator="LT" dataUnits="KB">
                <values val="50"/>
            </criteria>
        </whereClause>
    </queries>
</databrowse_BrowseRequest>

This example uses two whereClause structures to filter on two different fields (file modification date and file size). Again, the value you enter for ModifiedDate is the number of seconds since January 1, 1970 (standard Unix timestamp format). The output of this command provides its date information in Unix format. And of course the dataUnits value can be any of the supported units listed under <criteria dataUnits> in the Supported Elements and Parameters Used in Index Queries table.

Find Files Modified Yesterday

This XML template returns a list of file metadata, for files modified the previous day, starting at the path folder.

To run this query, follow the steps described in General Procedure, using the find_files_modified_yesterday_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="indexingstorage_4" subclientName="sc5" backupsetName="scale_bkp" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\**\*"/>
    <queries queryId="0" type="DATA">
        <whereClause>
            <criteria field="ModifiedDate" dataOperator="IN">
                <values val="Yesterday"/>
            </criteria>
        </whereClause>
    </queries>
</databrowse_BrowseRequest>

You may have noticed that you could actually get the same results by using the Find Files by Modification Date query, just by setting the modification date to yesterday's date. This form of query is provided to simplify that operation. See the values entry in the Supported Parameters Used in these Queries table to see the supported values for this form of date filtering.

You can also modify the behavior of this query by changing some of its values in the XML, such as changing the value to criteria field="ModifiedDate" to field="CreatedDate" to test for files that were created yesterday, rather than modified yesterday. Supported Parameters Used in these Queries provides a list of values supported by this test.

Get a Count of Archived Files

This XML template returns a count of files that have been archived, recursively in folders starting at the folder you specify.

To run this query, follow the steps described in General Procedure, using the count_archived_files_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="indexingstorage_4" subclientName="sc5" backupsetName="scale_bkp" appName="File System" _type_="0"/>
    <paths path="\**\*"/>
    <queries queryId="1" type="AGGREGATE">
        <aggrParam aggrType="COUNT" field="FileName"/>
        <whereClause connector="AND">
            <criteria field="StubbedObject" dataOperator="IN">
                <values val="ShowOnly"/>
            </criteria>
        </whereClause>
    </queries>
</databrowse_BrowseRequest>

The result of this operation is a count of files that are in an archived state (that is, a count of stubs), recursively, starting at the path specified. It appears in the XML structure as <aggrResultSet result="5"/>, where the actual count of files is indicated where this example shows the "5".

You can modify the some of the behaviors of this query by changing some of its values in the XML, such as changing the value to dataUnits="KB" to test for file size in kilobytes rather than megabytes. See Supported Parameters Used in these Queries.

Output of This Query

This query, with its queries type of AGGREGATE produces a different output than the type=DATA queries documented on this page. The output is found in the aggrResultSet element, such as this example: aggrResultSet result="5", where 5 is the number of archived files found.

Browse for the Largest Files in One Folder

As supplied, this XML template returns the names of the two largest files in a folder. This query, being based on the Browse operation type, is not recursive. It uses the SQL TOPBOTTOM function for its query type, which has parameters to control the data it returns.

To run this query, follow the steps described in General Procedure, above, using the browse_largest_files_template.xml file.

Example

Here is an example of XML for this query, showing sample values in the required parameters:

<databrowse_BrowseRequest opType="Browse">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\test_docs\"/>
    <queries queryId="TOPBOTTOM" type="TOPBOTTOM">
        <topBottomParam ascending="" count="2" field="FileSize"/>
    </queries>
    <mode mode="2"/>
</databrowse_BrowseRequest>

In this example, the TOPBOTTOM parameters are set to ascending="", and count="2". Setting the parameters this way returns the two largest files in the folder. See Supported Parameters Used in these Queries for the parameter settings.

Output of This Query

This query, with its queries type of TOPBOTTOM does not include the version parameter in its output. The other parameters are the same as the queries that use type=DATA. (See XML Output.)

List the Available Versions of a File

This XML template returns a list of the available versions of a file, in the folder you specify (this query is not recursive).

To run this query, follow the steps described in General Procedure, using the list_versions_of_file_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Versions">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\test_docs\create client steps log.txt"/>
    <queries queryId="0" type="DATA">
    </queries>
    <mode mode="2"/>
</databrowse_BrowseRequest>

You can modify the some of the behaviors of this query by changing some of its values in the XML, such as changing the value to dataUnits="KB" to test for file size in kilobytes rather than megabytes. See Supported Parameters Used in these Queries.

Supported Elements and Parameters Used in Index Queries

As supplied, the templates perform as described. However, you can change certain behaviors by modifying the values shown in this table if they appear in the template for that query. This list is not exhaustive, but a selection of the most common parameters you might want to use.

Parameter Description Values
queries type="type" Required. An element where you specify the kind of query to perform. Optionally, can begin a structure for entering test criteria. type can be set to:
  • DATA, to receive an alphabetically sorted list of file and folder metadata.
  • TOPBOTTOM, to receive a number of rows from the top or bottom of a sorted list of file and folder metadata. TOPBOTTOM queries imply a sort order, and use the topBottomParam element to specify the particulars of the query. topBottomParam supports these values:
    • ascending, determines the sort order. Valid values are "TRUE" and "" (null, which interprets as false)
    • count ="count"
    • field ="field_name" (see field names listed in XML_Output)
  • AGGREGATE, to receive a value that results from the application of logic across returned metadata. Available logic operators include:
    • MAX, the maximum numeric value for the numeric field specified in all returned file or folder metadata rows.
    • MIN, the minimum numeric value for the numeric field specified in all returned file or folder metadata rows.
    • AVG, the mathematical average of the numeric field specified in all returned file or folder metadata rows.
    • SUM, the mathematical sum of the numeric field specified in all returned file or folder metadata rows.
    • COUNT, the number of rows returned that met the specified testing criteria.
    • TOP, the first row of metadata in the results.
    • BOTTOM, the last row of metadata in the results.

    These operators are case-sensitive. Be sure to enter them in all capital letters, as shown.

whereClause structure Provides a structure into which you can put one or more tests through which data is filtered. A query can have multiple whereClause structures.
whereClause connector="connector" Defines the relationship between multiple "where" clauses. Required in whereClauses after the first one when using more than one.
  • AND
  • OR
criteria field="fieldname" Names the file metadata field to test.
  • FileSize, the size of a file. Folders return a FileSize of "0" (zero).
  • FolderSize, the size of a folder.
criteria dataOperator="operator" Defines the relationship of the tested field to the value being tested against. Numeric: GT and LT

Alphanumeric: relationship tests supported by SQL (LIKE, IN)

criteria dataUnits="unit" Defines the units to apply to the value. KB, MB, GB TB, PB
values val="value" The value to test the field against.
  • For numeric tests, must be an ASCII-coded integer.
  • For alphanumeric tests, numbers and letters are valid, though they are constrained by the valid characters for that field (for example, a slash character is not valid when testing for a file name, though a wildcard is if valid for the LIKE operator).
  • If the test uses <criteria dataOperator> of "IN", such as with the Find Files Modified Yesterday example, supported values for this parameter include:
    • Today
    • Yesterday
    • ThisWeek (encompasses Sunday through Saturday)
    • ThisMonth
    • ThisYear
    • LastWeek
    • LastMonth
    • LastYear
topBottomParam count="number" The number of results to be returned by a TOPBOTTOM operation. A nonzero integer
topBottomParam ascending="option" Controls whether the largest or smallest files are returned by a TOPBOTTOM operation.
  • True returns the smallest values
  • False (or null) returns the largest values
timeRange structure A structure in which to place a backup fromTime and toTime to filter on. Its structure is:

<timeRange>
    <fromTime>date</fromTime>
    <toTime>date</toTime>
</timeRange>

See the descriptions for
  • fromTime
  • toTime
fromTime A starting date (and optional time) of a range when the backup was taken. Any valid date in the format "Mmm dd, yyyy" or "yyyy-mm-dd". Time of day is optional, in hh:mm:ss format, such as "Dec 03, 2013 19:05:00". Template value is null.
toTime A ending date (and optional time) of a range when the backup was taken. Any valid date in the format "Mmm dd, yyyy" or "yyyy-mm-dd". Time of day is optional, in hh:mm:ss format, such as "Dec 04, 2013 04:55:00". Template value is null.
ModifiedDate values val=date The time when a file was last modified. Any valid Unix timestamp value, consisting of a number of seconds counted from January 1, 1970, such as "1399420800" (May 6, 2014 20:00:00 EDT).
options structure A structure in which to place various available options. Its structure is:

<options>
    <option_name>value</option_name>
</options>

Any available option, such as the restoreIndex, showDeletedFiles and caseInsensitive options listed in this table.
options restoreIndex If the index is not available, restore it or abort the query. true or null, where true means restore the index rather than abort.
options showDeletedFiles Include erased files in the results. true or null, where true means include the erased files.

Erased files are identified in the XML output by a deleted="1" field in the <flags> element.

options caseInsensitive When testing literal values, such as file name, ignore character case. true or null, where true means do not consider character case. Default is null.
ma client_name The fully qualified domain name of the MediaAgent computer. This needs to be the host name as specified in the CommCell Console. A valid fully qualified domain name.
dataParam Provides a structure by which to control paging and sorting of the XML query result file.
  • <paging> structure
  • <sortParam> structure
paging structure Set into a <dataParam> structure, controls the presentation of the data. Its structure is:

<queries ...>
    <dataParam>
        <paging>
            <firstNode>0</firstNode>
            <pageSize>10000</pageSize>
            <skipNode>0</skipNode>
        </paging>
    </dataParam>
</queries>

See the descriptions for
  • paging <firstNode>
  • paging <pageSize>
  • paging <skipNode>
sortParam structure Set into a <dataParam> structure, controls how the data is sorted in the output XML file. Its structure is:

<queries ...>
    <dataParam>
        <sortParam>
            <ascending>true</ascending>
            <sortBy>Flags</sortBy>
            <sortBy>FileName</sortBy>
        </sortParam>
    </dataParam>
</queries>

See the descriptions
  • sortParam <ascending>
  • sortParam <sortBy>
paging <firstNode> Sets the number of the first result row in the output XML file. Integer value including 0 (zero)
paging <pageSize> Sets the number of rows to place into the output XML file. Nonzero Integer value
paging <skipNode> Sets the number of returned rows to skip before writing to the output file. Integer value including 0 (zero)
sortParam <ascending> Controls the order in which the returned data is sorted. true or false. See the example in sortParam structure, above.
sortParam <sortBy> Names a field to use as a "by" clause in SQL. One or more field names, such as fileName or fileSize, to sort by. See the example in sortParam structure, above.
mode mode="n" Required for Browse operations. Retain the value supplied in each example template.

XML Output

The output of these queries is an XML file containing results. The structure of the results depends on the query being run, but in general, the element that contains the results is <dataResultSet>. It has these subfields:

Field Description
version The backed-up version number of the file. (Not included for queries that use <queries type="TOPBOTTOM"/>.)
size The size of the file, in bytes.
path The full path the file, including the file's name.
name The Windows internal name of the file, which includes some characters prepended to the name that you probably don't want. We recommend using displayName instead.
modificationTime The file's modification timestamp, in seconds offset from January 1, 1970 (Unix standard timestamp format).
displayName The file's name as displayed in Windows Explorer.
aggrResultSet result The result returned by queries using <queries type=AGGREGATE/>.

Important: When SQL errors occur, the SQL server also returns its error messages to the output XML file.

Getting Results in CSV Format

The queries described on this page all return their results in the form of an XML file. A Python script file is available for converting the XML-format files produced by most of these queries into a CSV (comma-separated value) file that can be read by scripts and other commercial software. Contact your software provider to obtain the script file.

Important: Two versions of the script file are available, one for Python 2.x, and one for Python 3.x. The examples below use the version 3.x script named xml2csv_3.py. If you are using Python version 2, use the script named xml2csv_2.py.

Converting XML Output to CSV

Follow these steps:

  1. Place the script file into a directory on the Windows or UNIX computer where you will run the conversion.
  2. For the examples below, we have named that directory xml2csv.

  3. Run the script using this command (on one line):

    python script_name -i xml_file -o csv_filename.csv

    Windows example:

    python c:\xml2csv\xml2csv_3.py -i c:\queryxmlout\find_123.xml -o c\querycsv\find_123.csv

    UNIX example:

    python /xml2csv/xml2csv_3.py -i /queryxmlout/find_123.xml -o /querycsv/find_123.csv

The script reads the XML file named in the -i option, then creates (or overwrites) the CSV file named in the -o option.

Important:

  • The input XML file must have an extension of .xml.
  • The output CSV file must have an extension of .csv.

CSV Output

The CSV file contains a selection of the metadata fields (name, path, modification date, etc.) for each file in the XML. The first line of the output file provides the fieldnames.

Limitations

The xml2csv script converts the output of all the examples here to CSV format except for Get a Count of Archived Files. The AGGREGATE query type used to get the count returns only a single numeric result, not a <dataResultSet> element. Feeding the XML output from an AGGREGATE query into the script will produce a CSV file containing only a header record (that is, no data records).